backend-api-design

后端 API 设计——快速参考

URL 模式

GET  /api/v1/employees              # List (plural)
GET  /api/v1/employee               # Get one (?id=xxx)
POST /api/v1/employee               # Create
POST /api/v1/employee/update        # Update (?id=xxx)
POST /api/v1/employee/delete        # Soft delete (?id=xxx)
POST /api/v1/employee/restore       # Restore (?id=xxx)
POST /api/v1/sync/employees         # Action

硬性规则

• 禁止使用路径参数——始终使用 @QueryValue，绝不使用 @PathVariable
• 单个资源使用单数形式——使用 /employee，而非 /employees/{id}
• 集合使用复数形式——使用 /employees
• 操作使用动词子路径——/delete、/restore、/sync

分层架构

Controller  →  thin, just delegates
    ↓
Manager     →  business logic, transactions, Either returns
    ↓
Repository  →  data access only, no business logic

Controller：精简封装

• 使用默认值解析查询参数
• 委托给 manager
• 使用 .throwOrValue() 解包 Either
• 不包含业务逻辑，也不访问 repository

Manager：业务逻辑

• 返回 Either<ClientException, T>
• 使用 transaction(db.primary) { } 封装数据库操作
• 协调多个 repository
• 验证业务规则

Repository：数据访问

• 返回实体或 null
• 读取使用 db.replica，写入使用 db.primary
• 始终检查 deletedAt.isNull()

代码快速参考

核心 controller 委托模式：

@Get("/employee")
suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse {
  return employeeManager.findById(id).throwOrValue()
}

• 响应模型——在 module-client/response/{domain}/ 中使用 companion object { fun from(entity) }
• 分页——基于 offset；manager 返回包含 items、total、page、limit、hasMore 的 EmployeeListResponse
• 错误——manager 返回 ClientError.NOT_FOUND.asException().left()，绝不抛出异常
• Factory bean——使用包含 @Singleton 方法的 @Factory 类，将 repos 和 db 连接到 manager

完整的 controller、响应模型、分页、错误处理和 factory bean 模板，请参阅 code-patterns.md。

易错点

• 多词 @QueryValue 参数必须显式指定 snake_case 名称。 前端 axios 拦截器发送 project_id，但 Micronaut 会匹配参数的字面名称。应写为 @QueryValue("project_id") projectId: UUID，而不是单独使用 @QueryValue projectId: UUID。
• 不要使用 @Put、@Delete 或 @Patch。 这是 RPC 风格——所有变更操作都使用 @Post。只有读取操作使用 @Get。
• Controller 注入 repository 是一种代码异味。 如果你在 controller 中看到 private val fooRepository: FooRepository，请将它移到 manager 中。
• 使用 andWhere {}，而不是第二个 .where {}。 再次调用 .where {} 会替换第一个条件。使用 .andWhere {} 链接条件。
• 别忘了 @ExecuteOn(TaskExecutors.IO)。 缺少它时，挂起函数可能会卡住，或在错误的线程池上运行。每个 controller 都需要它。