---
description: {一句话：后端 API 层开发约定}
globs: {如 "src/api/**"，按实际目录}
---

<!-- 模板骨架 · 生成时遵守四原则，{占位符} 结合项目填充。
     cm-backend-engineer 的默认值（超时/分页等）以本文件为准 -->

# 后端 API 规范

## 分层与路由

- 分层：{controller/service/repository 或项目实际分层，附目录}
- 路由组织：{按资源分组的实际方式}；新路由必须显式挂鉴权中间件或声明公开

## 错误处理

- 统一错误体结构：`{ code, message, ... }`（{附项目实际结构}）
- 全局错误处理器统一出口，禁止 handler 内裸造错误体
- 错误码清单位置：{路径}

## 输入与幂等

- 边界层校验：{校验库}；内层信任已校验数据
- 写操作幂等：{幂等键方案}；支付类接口强制

## 性能与可靠性默认值

- 外部调用超时：{5}s；重试上限：{N} 次
- 列表接口必须分页，默认页大小 {20}，上限 {100}
- 缓存策略：{Redis/内存缓存的使用边界}

## 可观测

- 日志格式与脱敏：{约定，敏感字段清单}
- {链路追踪/健康检查端点约定}