API 约定

每个 StackRivet 端点——包括代码生成器产出的——都遵守同一套约定，base path 为 /api/v1。详尽的端点目录是当前运行实例生成的 OpenAPI 3.1 文档；本页是这些端点共享的契约。

# 仅用于全新本地数据库——使用本地种子凭据，不使用在线 Demo 凭据。
STACKRIVET_LOCAL_ADMIN_PASSWORD=stackrivet2026
TOKEN=$(curl -s http://127.0.0.1:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"username\":\"admin\",\"password\":\"${STACKRIVET_LOCAL_ADMIN_PASSWORD}\"}" | jq -r '.data.accessToken')

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/v3/api-docs
unset STACKRIVET_LOCAL_ADMIN_PASSWORD TOKEN

如果没有 jq，从登录响应里复制 data.accessToken 即可。该示例刻意只访问 127.0.0.1；不要将本地种子密码复用于在线 Demo 或已部署实例。如果在线 Demo 开放访问，其凭据会在登录页单独说明。

响应信封

每个响应都被包装，并带一个可与服务端日志关联的 traceId：

{ "code": "0", "message": "OK", "data": {}, "traceId": "01J..." }

code: "0" 表示成功。注意 HTTP 状态码同样有意义（StackRivet 不把一切都压成 200）——code 是稳定、可被机器分支的契约，HTTP 状态是传输层信号。

分页的 data：

{ "items": [], "page": 1, "pageSize": 20, "total": 0 }

HTTP 状态码

状态	何时
200 / 201	成功 / 已创建
400	参数错误
401 / 403	未认证 / 无权限
404	不存在
409	状态 / 唯一键 / 版本冲突
413 / 415	上传过大 / 类型不支持
429	限流
500	系统错误

错误码

错误 code 是稳定、永不本地化的契约——客户端按它分支。传输格式为 {前缀}_{原因}_{HTTP}：

{ "code": "SYSTEM_USER_DUPLICATED_409", "message": "...", "details": [], "traceId": "01J..." }

前缀包括 AUTH、PERM、VALIDATION、SYSTEM、ASSET、SIGNED_URL、GENERATOR、TASK。所有码来自 stackrivet-common 的 ErrorCode 注册表；message 按 Accept-Language 本地化（回退英文），但 code 不。构建期门禁保证每个码的中英文案齐备。

分页与排序

参数	默认	说明
`page`	1	从 1 开始
`pageSize`	20	最大 200
`sort`	—	如 `createdAt,desc`；仅白名单字段

sort 只接受白名单字段——任意 SQL 列绝不透传。

类型

时间是 ISO 8601 字符串。
精度敏感值（金额、比例）用字符串或整数最小单位——绝不用浮点。
枚举是小写字符串；布尔是 JSON boolean；ID 是字符串。

请求头

Authorization: Bearer <access_token>
X-Request-Id: 可选的客户端请求 ID

Token 短期有效且可撤销；强制下线使旧 token 失效。Token 绝不进日志。
只有接口明确声明支持幂等时才发送幂等键。任务提交在 JSON body 中携带 idempotencyKey，避免重试导致同一任务重复执行。
任务提交返回 201 和任务资源；运行、取消、重试是显式任务动作。通过任务追踪状态。

API 分组

OpenAPI tag 映射到路径前缀：Auth（/auth）、Me（/me）、Users、Departments、Posts、Roles、Menus、Dictionaries、Params、Audit、Assets、Generator、Tasks、System——全部在 /api/v1 下。