目录一、架构与命名规范REST 优先1. 资源命名原则2. HTTP 方法语义严格对应二、请求参数设计原则1. 参数位置区分2. 统一参数规范三、统一返回格式最重要协作原则标准返回模板四、异常与错误处理原则五、安全设计原则六、兼容性与版本迭代原则七、性能与资源约束原则八、文档、可观测原则九、拓展RPC 接口补充微服务内部极简总结开发快速记忆分架构规范、REST 风格、参数规范、安全、兼容性、文档、性能七大模块后端开发通用标准前后端协作、微服务都适用。一、架构与命名规范REST 优先1. 资源命名原则名词复数表示资源集合不用动词 错误/getUser/addOrder正确查询用户列表GET /users单个用户GET /users/{id}创建订单POST /orders修改订单PUT /orders/{id}删除订单DELETE /orders/{id}层级资源用嵌套路径/users/{userId}/orders用户下的所有订单全部小写横杠-分隔禁止下划线、驼峰 正确/user-address错误/userAddress/user_address统一接口前缀区分业务 / 版本版本放路径推荐/api/v1/users不建议放 header / 参数可读性差2. HTTP 方法语义严格对应Method作用使用场景GET查询只读获取列表、详情无副作用POST新增 / 复杂提交创建资源、登录、批量操作PUT全量更新覆盖整条资源PATCH局部更新只修改部分字段DELETE删除资源逻辑 / 物理删除硬性约束GET 不能修改数据POST 不能用于单纯查询幂等区分GET/PUT/DELETE 天然幂等POST 非幂等重复调用会重复创建。二、请求参数设计原则1. 参数位置区分路径参数Path唯一标识资源 ID/users/1001查询参数Query筛选、分页、排序GET 专用/orders?page1size10statuspaid请求体 BodyPOST/PUT/PATCH 复杂对象、批量数据 GET禁止携带 Body部分网关、Nginx 会丢弃。2. 统一参数规范分页参数全局统一page页码默认 1size每页条数限制最大值如最多 100sort排序字段sortcreateTime,desc过滤参数统一命名status、startTime、endTime字段命名统一后端统一下划线 / 驼峰二选一前后端约定好不混用不传参数不赋默认值后端判空处理禁止前端传null/ 空字符串混用ID 类数字大值雪花 ID返回字符串避免 JS 精度丢失三、统一返回格式最重要协作原则全局固定结构前端不用多套解析逻辑标准返回模板{ code: 200, // 业务状态码 msg: success, // 提示文案 data: {}, // 业务数据无数据返回null traceId: xxx // 链路追踪ID排查日志必备 }code 分层设计200成功4xx客户端错误参数缺失、权限不足、未登录5xx服务端异常数据库、内部报错自定义业务码10001 用户不存在、10002 密码错误HTTP 状态码与业务 code 配合查询成功HTTP 200创建成功HTTP 201参数错误HTTP 400未登录401无权限 403资源不存在404服务异常500列表分页统一返回结构data: { records: [], total: 132, page: 1, size: 10 }删除 / 无返回操作 data 返回null不省略字段四、异常与错误处理原则禁止直接抛数据库原生异常、堆栈给前端错误 msg 分两种给用户简洁易懂“手机号格式错误”后台日志完整异常栈 traceId参数校验统一返回批量校验返回所有错误字段不遇到一个就中断{ code: 400, msg: 参数校验失败, data: [ {field:phone,message:手机号长度必须11位} ] }五、安全设计原则身份认证统一统一 Token 放在 HeaderAuthorization: Bearer xxx不放在 url 参数日志泄露权限控制接口层校验接口访问权限、数据行权限越权校验只能操作自己的数据防攻击入参统一过滤 XSS、SQL 注入敏感数据加密传输HTTPS 强制接口限流防刷单 IP / 单账号 QPS 限制敏感信息脱敏 手机号、身份证、银行卡返回脱敏不明文输出日志、响应防重放接口加时间戳 签名 sign防止请求被劫持重复调用六、兼容性与版本迭代原则接口向前兼容核心原则新增字段不能删除原有字段新增字段默认允许为空不修改现有字段含义、字段类型枚举值只能新增不能删除旧枚举重大不兼容改动升级版本/api/v2/xxx废弃接口规范header 返回Deprecation: true文档标注下线时间过渡期保留七、性能与资源约束原则分页强制限制最大 size禁止一次性查全表大列表支持按需字段投影fieldsid,name减少返回冗余字段批量操作限制单次最大条数如批量创建最多 200 条大文件 / 大数据流不通过 JSON 返回提供文件下载接口高频查询接口增加缓存避免频繁查库八、文档、可观测原则强制生成接口文档Swagger/Knife4j/OpenAPI 标注接口作用、入参、出参、错误码、示例全链路埋点traceId、请求耗时、入参日志脱敏接口分级内部接口 / 对外开放接口区分对外接口额外限流鉴权九、拓展RPC 接口补充微服务内部如果是 Dubbo/GRPC 内部接口额外遵循方法动词命名getUserById、batchSaveOrder请求 / 响应体单独建 DTO不复用数据库实体超时时间统一配置强制重试、熔断降级入参必传字段注释不能传 null 的对象提前约定极简总结开发快速记忆REST 语义清晰名词资源、HTTP 方法各司其职全局统一请求、分页、返回体格式入参严格校验错误信息标准化HTTPS 统一鉴权脱敏防越权防重放迭代向前兼容不破坏老业务限流分页控数据量兼顾性能配套完整文档与日志追踪。