Nhảy đến nội dung chính

Cách dùng skill spring-boot-api-flow

1.  Cài đặt ban đầu — Clone thư mục .agent

Trước khi sử dụng skill, bạn cần clone repository cấu hình về thư mục gốc của project bằng lệnh sau:

git clone -b master http://192.168.0.95/minhnd/chat-gpt-agent.git .agent

Lệnh trên sẽ tải branch master và đặt toàn bộ nội dung vào thư mục .agent ngay trong thư mục hiện tại của bạn.

Lưu ý:  Chạy lệnh này tại thư mục gốc (root) của project, không phải bên trong thư mục con nào khác.

2.  Hướng dẫn cài đặt Google Antigravity

image.png


Sau đó cài đặt như bình thường.

3.  Mục tiêu của Skill

Skill này được thiết kế để:

•       Chuẩn hóa cấu trúc dự án Spring Boot.

•       Đảm bảo tính nhất quán (Consistency) giữa các module.

•       Tự động hóa việc ra quyết định về kiến trúc (Layered Architecture).

•       Tuân thủ các quy tắc bảo mật và lưu vết (Audit log).

4.  Cách kích hoạt (Activation)

Skill này hoạt động hoàn toàn TỰ ĐỘNG khi project có thư mục cấu hình .agent.

Cơ chế:  Khi bạn gửi các SRS, CSDL, config db, kèm theo yêu cầu (ví dụ: "Render API chuẩn spring boot"), hệ thống nhận diện .agent, kích hoạt @backend-specialist và tự động áp dụng các quy chuẩn trong skill spring-boot-api-flow.

Lưu ý:  Bạn không cần copy nội dung skill vào chatbot, chỉ cần đảm bảo thư mục .agent nằm trong project.

 

 

5.  Các Quy tắc "Vàng" (Mandatory Rules)

Cần tuân thủ 5 quy tắc bắt buộc sau khi viết code:

  1. Kiến trúc 3 lớp:  Luôn tuân theo luồng Controller -> Service -> Repository.
  2. Không Logic ở Controller:  Controller chỉ nhận request, check validation cơ bản và gọi Service.
  3. ApiResponse Standard:  Mọi API phải trả về object ApiResponse<T>. Không trả về trực tiếp DTO hay Entity.
  4. DTO vs Entity:  Tuyệt đối không trả về Entity cho Client. Luôn dùng DTO cho Request và Response.
  5. In-memory Storage:  Dùng ConcurrentHashMap hoặc List trong Repository nếu chưa có Database bên ngoài.

5b.  Cấu trúc Module chuẩn

Mỗi module mới khi tạo ra phải có cấu trúc thư mục như sau:

modules/<module-name>/

  +-- controller/   (Chua @RestController)

  +-- service/      (Chua Business Logic & Interface)

  +-- repository/   (Chua truy van du lieu)

  +-- entity/       (Chua mapping du lieu)

  +-- dto/          (Chua Request/Response models)

 

6.  Quy trình phát triển 5 bước (API Workflow)

Để tạo một tính năng mới, hãy đi theo trình tự:

  1. B1: Tạo DTO:  Định nghĩa Request và Response model.
  2. B2: Tạo Entity:  Định nghĩa cấu trúc dữ liệu mapping.
  3. B3: Tạo Repository:  Định nghĩa các phương thức lưu trữ dữ liệu.
  4. B4: Tạo Service:  Viết Business Logic (Xử lý dữ liệu, chuyển đổi Entity <-> DTO).
  5. B5: Tạo Controller:  Khai báo Endpoint và gọi Service.

7.  Coding Convention (Quy tắc đặt tên)

Bảng quy ước đặt tên các thành phần trong dự án:

Thành phần

Quy tắc đặt tên

Ví dụ

Controller

<n>Controller

UserController

Service

<n>Service

UserService

Repository

<n>Repository

UserRepository

Entity

<n>Entity

UserEntity

DTO Request

<n>CreateRequest

UserCreateRequest

DTO Response

<n>Response

UserResponse

 

8.  Ví dụ một phương thức Service chuẩn

Dưới đây là cấu trúc chuẩn của một phương thức trong Service layer:

public UserResponse create(UserCreateRequest request) {

 

    // 1. Validate (Kiem tra du lieu)

    if (repo.existsByUsername(request.getUsername())) {

        throw new BusinessException(ErrorCode.USER_EXISTS);

    }

 

    // 2. Log (Luu vet hanh dong)

    log.info("Creating user: {}", request.getUsername());

 

    // 3. Business logic (Xu ly)

    UserEntity entity = mapper.toEntity(request);

    repo.save(entity);

 

    // 4. Return (Tra ve ket qua)

    return mapper.toResponse(entity);

}

 

Lên đầu trang