二、接口设计规范与最佳实践归纳总结
政务项目里，接口乱象是最让人头大的问题之一。
我接手过不少这样的项目——接口命名五花八门，参数一会儿下划线一会儿驼峰，状态码随心所欲。你敢信？有次看到个接口返回 200，body 里却放着 {"code": -1, "msg": "系统异常"}。
嗯，这种坑踩一次就够了。今天我把这些经验整理成一套可落地的规范，希望能帮你少走弯路。
2.1 RESTful 风格的核心骨架
政务系统和互联网不太一样。我们不能照搬 REST 的所有条款，但核心思路一定要对齐。
说白了就是：用资源视角看接口，而不是动作视角。
- 动词要谨慎：只用 GET、POST、PUT、DELETE。我见过有人用 POST 做查询，用 GET 做删除……那叫一个酸爽。
- URI 只表示资源：
/api/v1/approvals表示审批单，而不是/api/getApprovalList。 - 状态码用标准语义：200 成功，201 创建，400 参数错误，401 未认证，403 无权限，500 服务端异常。
🔑 核心原则： 接口是契约，不是随便写的纸条。一旦上线，改起来代价极高。
我习惯用这张表来对齐团队共识：
| HTTP 方法 | 资源操作 | 典型场景 | 常见乱用 |
|---|---|---|---|
| GET | 查询 / 列表 | 获取审批列表、用户详情 | POST 做查询，传大量 body 参数 |
| POST | 创建 / 提交 | 新增审批单、提交工单 | POST 改数据、POST 删数据 |
| PUT | 全量更新 | 更新审批单全部字段 | PUT 部分字段，该用 PATCH |
| DELETE | 删除 | 删除草稿、取消申请 | GET 带删除参数 |
💡 我的小技巧： 在团队 Wiki 里贴这个表，每次 CR（代码评审）时对着检查。坚持一个月，接口质量肉眼可见提升。
2.2 字段与数据类型设计
你想想看，一个明明能填 “0” 的字段，非要传 null，前端崩溃不？
我在项目里遇到过：某个字段叫 status，有人传 0，有人传 “0”，有人传 “待审核”，还有人直接不传。最后每次查数据都要做三层空值处理，累得慌。
这里我总结了几条铁律：
- 命名统一用下划线：数据库字段
approval_status，接口也保持一致。我之前跟一个数据中台对接，对方传了approvalStatus，结果前端用的是approval_status……对不齐，崩了。 - 类型明确且不模糊：能用 int 就别用 string，能用 boolean 就别用 int（0/1）。我记得有个项目用 int 表示启用/禁用，结果有人传了 2，系统直接报错。
- 空值策略前置约定：null 和 空字符串 到底等不等？我的建议是：字符串不传 null 只传空串
""，数字不传 null 只传 0，布尔不传 null 只传 false。 - 时间统一用 ISO 8601：例如
2025-03-18T14:30:00+08:00。不要再用时间戳了，前端维护起来太痛苦。
⚠️ 特别注意： 时间戳必须在文档里写清楚单位。秒还是毫秒？我曾经因为这个问题让一个审批节点跑到了 2077 年……
2.3 安全与版本规范
政务项目对安全的要求比其他领域高得多。接口一旦暴露，数据泄露就是大事。
我个人的习惯是：安全规范不是可选项，是必选项。
- 身份认证：走 JWT 或 OAuth2， 必须有过期时间。不要在 URL 里传 ，更不要明文传密码。
- 敏感数据脱敏：身份证、手机号、银行账号，接口响应里必须脱敏。例如
138****1234。 - 参数校验：服务端一定要做白名单校验，别全依赖前端。我见过一个接口只在前端校验了必填项，结果一个恶意请求直接灌入了 10 万条脏数据。
- 版本管理：URI 里带 v1、v2。不要用 Header 控制版本，运维和网关太难接。
🔒 安全规范一句话： 接口上线前，先问自己三个问题——这条数据别人能看到吗？这个请求能被伪造吗？参数溢出会怎么样？
2.4 一套可复用的发布避坑清单
我曾经把一个接口改了字段类型，没通知前端，直接上线了……结果全站点了两天 bug。从那以后，我每次发布前都要过一遍这个清单：
- 我改过字段名吗？ 如果改了，一定要给前端留一个版本并行期。
- 我改过字段类型吗？ 比如从 string 改成 int，前端不感觉得到才怪。
- 我删过字段吗？ 如果旧的调用方还在用，直接报错。
- 新增接口有文档吗？ 没文档的接口等于不存在。
- 异常情况测试过了吗？ 比如参数超长、空值、并发超限。
✅ 省心做法： 把这个清单做成 Git Hook，每次 commit 前自动检查。团队统一执行，比贴纸贴在墙上管用多了。
2.5 一张图看懂接口设计规范全景
我把上面这些内容串成一个结构图，方便你对照执行：
说了这么多，其实核心就一句话：规范不是束缚，是给你省事的工具。前期多花半小时对齐，后期能省三天排查。我在多个项目里验证过这一点，百试不爽。