接口规范与统一响应

{
  "httpStatus": 200,
  "code": "A0000",
  "message": "success",
  "userMessage": null,
  "data": {},
  "requestId": "trace_xxx",
  "path": "/api/example",
  "timestamp": "2026-03-25 10:00:00"
}

字段解释：

httpStatus：HTTP 状态码镜像，便于前端统一处理
code：业务响应码
message：面向排障的技术描述
userMessage：面向最终用户展示的提示
data：业务载荷
requestId：链路追踪 ID
path：当前请求路径
timestamp：响应时间戳

文件下载、流式响应可以例外，但依然要保留鉴权和审计约束。

HTTP 状态码与业务码

常用 HTTP 状态建议：

200：请求被正常处理
400：参数错误
401：未认证
403：无权限
404：资源不存在
409：资源冲突
429：限流
500：系统异常
503：服务不可用或降级

业务码建议分层：

A0000：成功
B1xxx：认证与权限
B2xxx：业务风控与配额
B3xxx：参数与校验
B4xxx：资源状态与冲突
B5xxx：文件与导入导出
B6xxx：限流、幂等、防刷
Cxxxx：系统和依赖异常

请求头规范

建议统一支持：

Authorization
X-Request-Id
X-Client-Type
X-App-Version
Accept-Language

这些头的价值在于：

Authorization 负责认证
X-Request-Id 贯穿排障链路
X-Client-Type / X-App-Version 方便兼容多端行为
Accept-Language 便于国际化响应或提示文案

分页规范

请求建议统一为：

{
  "current": 1,
  "pageSize": 20,
  "sorter": {
    "createdAt": "descend"
  },
  "filters": {
    "status": [1],
    "keyword": "admin"
  }
}

响应建议统一为：

{
  "code": "A0000",
  "message": "success",
  "data": {
    "list": [],
    "total": 0,
    "current": 1,
    "pageSize": 20
  }
}

约束：

分页大小必须限制
禁止超大分页直接扫表
列表默认要带排序语义
高频列表要结合索引设计

写接口规范

创建用 POST
整体更新用 PUT
局部状态更新用 PATCH
删除用 DELETE

导入导出、批量操作、状态切换这类动作，要么走资源语义清晰的路径，要么走明确的任务型接口，不要全部混成一个“万能 POST”。

参数校验规范

所有写接口必须做服务端校验
失败时返回统一业务码和可定位字段信息
不能依赖前端校验作为安全边界

前端校验负责交互体验，后端校验负责系统正确性。

幂等与防重复提交

以下动作要重点考虑幂等保护：

创建
审批
导入
导出
发送
状态切换

重复提交时应返回统一业务码，而不是直接抛通用异常或默默生成重复数据。

权限与数据范围

接口入口做功能权限校验
数据访问层做数据范围过滤
高风险操作写审计日志

这里最常见的误区是：前端按钮隐藏了，就以为接口也安全了。实际上后端接口必须独立完成真实鉴权。

文件与流式接口

上传统一 POST /api/v1/files/upload
下载必须先鉴权、再审计、再输出流
私有文件建议使用签名或代理下载

如果是知识库、插件、导出报表等文件，更应该保留元数据和访问审计，不要直接裸链暴露。

导入导出与任务接口

导入导出尽量任务化，至少分成三类接口：

任务创建
任务状态查询
任务结果查询

大文件和复杂报表不要同步阻塞请求线程，这类场景更适合通过任务中心和异步链路承载。

开放接口预留

建议使用 /openapi/v1/*
使用独立签名、时间戳、重放保护、限流和调用日志
内部接口和开放接口必须边界清晰

不要把内部后台接口直接暴露给第三方调用。

开发红线

不要让同一业务域同时存在多种响应壳
不要把所有读取都写成 POST
不要省略 requestId
不要把默认堆栈或数据库异常原样返回给前端
不要跳过权限、幂等和审计要求

接口规范与统一响应

目录