Sản phẩm nhà. Plugin này do ShipWithAI xây dựng và duy trì. Khác với các tool bên thứ ba được review trong toolkit, đây là sản phẩm của chính chúng tôi — hãy đọc với tinh thần đó.
Vấn đề nó giải quyết
Các skill pack Spring Boot thông thường vừa đồ sộ vừa thụ động: một tài liệu tham chiếu lớn, chỉ
được load khi tình cờ khớp keyword. Lúc model scaffold một @Entity, không có gì bảo đảm rule
“thêm @Version” sẽ chạy. Tri thức có tồn tại, nhưng không được kích hoạt đúng khoảnh khắc mắc lỗi.
Toolkit này đảo ngược điều đó. Một hook tất định chạy trên mọi lần sửa file Java và đưa ra advisory ngay khi một anti-pattern quen thuộc xuất hiện. Tài liệu tham chiếu ở đó để giải thích vì sao — nó không phải cơ chế chính.
Cách cài đặt
/plugin marketplace add ShipWithAI/shipwithai-plugins/plugin install shipwithai-java-backend-toolkit@shipwithaiSau đó chạy skill setup để nối guardrail hook vào project.
Cách sử dụng
Bốn cơ chế, xếp theo mức quan trọng:
- Guardrail hook —
hooks/jpa-guardrail.pychạy PostToolUse trênWrite/Editcủa*.java(vàapplication.properties/.ymlcho các rule cấu hình), rồi đưa advisory hoặc chặn. - Scaffold skills —
jpa-entity,spring-rest-endpoint,db-migration,rest-error-handler,idempotent-endpoint,security-filter-chain,jwt-auth,integration-test,test-slice. Sinh code không bao giờ chạm guardrail. - Knowledge skill —
springboot-conventions, chia theo domain: persistence, web, transactions, testing. - Reviewer agent —
springboot-reviewer, mà checklist của nó chính là ruleset.
Một phần những gì ruleset bắt được:
| Rule | Bắt lỗi gì | Mức |
|---|---|---|
jpa-optimistic-lock | @Entity không có @Version — mất update | warning |
tx-proxy | @Transactional trên method không public — âm thầm không được proxy | warning |
jpa-eager-fetch | association FetchType.EAGER — over-fetch và N+1 | warning |
jpa-osiv | spring.jpa.open-in-view=true — lazy load rò ra tầng view | warning |
nplus1-heuristic | gọi repository bên trong vòng lặp | info |
jpql-injection | query dựng bằng nối chuỗi | chặn |
Mẹo dùng
- Ưu tiên scaffold skill hơn là mô tả entity bằng lời. Code sinh đúng ngay từ đầu thì guardrail chẳng bao giờ phải lên tiếng.
- Khi hook báo một chỗ bạn tin là ổn, hãy đọc phần
springboot-conventionstương ứng trước khi bỏ qua — các rule này mã hoá những kiểu hỏng trông rất vô hại lúc review. - Giữ reviewer agent và hook cùng version. Cả hai dùng chung một ruleset, và đó chính là điểm mấu chốt.
Khi KHÔNG nên dùng
Không dành cho bất cứ thứ gì ngoài Spring Boot + JPA. Cũng không thay được test — nó bắt một nhóm lỗi cụ thể ở tầng persistence và web, còn logic nghiệp vụ của bạn thì nó im lặng.