name: allra-api-design description: Allra后端API设计及包结构规则。用于创建REST API、DTO或组织后端代码结构时使用。

Allra后端API设计及包结构

Allra后端团队的API设计、DTO命名、包结构标准定义。

项目基本信息

本指南基于以下环境编写：

Java: 17及以上
Spring Boot: 3.2及以上
主要技术: JPA/Hibernate, QueryDSL, JWT

注意: 各项目使用的技术栈或版本可能不同。请根据项目实际情况调整使用。

包结构规则

推荐按领域划分包结构：

└── {domain}
    ├── api          // 控制器层
    ├── dto          // 数据传输对象
    ├── entity       // JPA实体
    ├── enums        // Enum定义（可选）
    ├── repository   // 数据访问层
    └── service      // 业务逻辑

注意: 根据项目不同，可使用controller、model、dao等其他名称。重要的是明确各层级的职责分离。

示例

└── user
    ├── api
    │   └── UserController.java
    ├── dto
    │   ├── UserSignUpEventDto.java  // 内部使用
    │   ├── request
    │   │   └── SignUpRequest.java
    │   └── response
    │       └── SignUpResponse.java
    ├── entity
    │   └── User.java
    ├── repository
    │   ├── UserRepository.java
    │   └── UserRepositorySupport.java
    └── service
        └── UserService.java

DTO命名规则

1. 客户端通信DTO

Request: {操作}Request
- 例: SignUpRequest, UpdateUserRequest
Response: {操作}Response
- 例: SignUpResponse, UserDetailResponse

2. 内部使用DTO

仅内部使用的DTO添加Dto后缀：

Repository层QueryDSL Fetch DTO
内部层传输DTO
例: UserSignUpEventDto, UserSummaryDto

3. Record使用

DTO等简单类尽可能使用record创建

// Request/Response
public record SignUpRequest(
    String email,
    String password,
    String name
) {}

public record SignUpResponse(
    Long userId,
    String email
) {}

// 内部使用DTO
public record UserSignUpEventDto(
    Long userId,
    String email,
    LocalDateTime signUpAt
) {}

API控制器设计指南

1. REST API命名规则

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    // GET /api/v1/users - 列表查询
    @GetMapping
    public List<UserResponse> getUsers() { }

    // GET /api/v1/users/{id} - 单条查询
    @GetMapping("/{id}")
    public UserDetailResponse getUser(@PathVariable Long id) { }

    // POST /api/v1/users - 创建
    @PostMapping
    public SignUpResponse createUser(@RequestBody @Valid SignUpRequest request) { }

    // PUT /api/v1/users/{id} - 整体修改
    @PutMapping("/{id}")
    public UserResponse updateUser(
        @PathVariable Long id,
        @RequestBody @Valid UpdateUserRequest request
    ) { }

    // PATCH /api/v1/users/{id} - 部分修改
    @PatchMapping("/{id}")
    public UserResponse patchUser(
        @PathVariable Long id,
        @RequestBody @Valid PatchUserRequest request
    ) { }

    // DELETE /api/v1/users/{id} - 删除
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) { }
}

注意: API版本控制(/api/v1/...)根据项目政策选择性应用。

2. 请求验证

所有Request DTO使用Bean Validation：

public record SignUpRequest(
    @NotBlank(message = "邮箱为必填项")
    @Email(message = "邮箱格式不正确")
    String email,

    @NotBlank(message = "密码为必填项")
    @Size(min = 8, message = "密码至少8位以上")
    String password,

    @NotBlank(message = "姓名为必填项")
    String name
) {}

3. 响应格式

Allra标准格式（示例）：

成功响应：

{
  "data": { ... },
  "message": "请求处理成功"
}

错误响应：

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户不存在",
    "details": []
  }
}

注意: 响应格式可能因项目而异。保持格式一致性很重要。

使用场景

本skill在以下情况自动应用：

创建新API端点
编写DTO类
实现控制器
设计领域包结构
Request/Response对象命名

示例

示例1：创建新领域API

// 1. 包结构创建
kr.co.allra.product/
├── api/ProductController.java
├── dto/
│   ├── request/CreateProductRequest.java
│   └── response/ProductResponse.java
├── entity/Product.java
├── repository/ProductRepository.java
└── service/ProductService.java

// 2. Request DTO
public record CreateProductRequest(
    @NotBlank String name,
    @NotNull BigDecimal price
) {}

// 3. Response DTO
public record ProductResponse(
    Long id,
    String name,
    BigDecimal price,
    LocalDateTime createdAt
) {}

// 4. Controller
@RestController
@RequestMapping("/api/v1/products")
public class ProductController {

    @PostMapping
    public ProductResponse createProduct(
        @RequestBody @Valid CreateProductRequest request
    ) {
        return productService.createProduct(request);
    }
}

示例2：创建内部DTO

// QueryDSL结果用内部DTO
public record ProductSummaryDto(
    Long id,
    String name,
    Long orderCount
) {
    @QueryProjection
    public ProductSummaryDto {}
}

// 事件传递用内部DTO
public record ProductCreatedEventDto(
    Long productId,
    String productName,
    LocalDateTime createdAt
) {}

检查清单

创建新API时确认事项：

[ ] 是否遵循领域包结构？
[ ] Request/Response DTO命名是否遵循规则？
[ ] DTO是否使用record编写？
[ ] Request DTO是否应用了验证？
[ ] 是否遵循REST API命名规则？
[ ] 内部使用DTO是否有Dto后缀？