RESTful API 设计原则在政务场景的应用归纳
说实话，RESTful 原则在政务项目里经常被误解。有人觉得就是 URL 里用名词，有人觉得必须严格遵循 HATEOAS。我自己的体会是：政务场景下，实用比纯粹更重要。下面我把这几年踩过的坑、总结出的经验，按几个核心原则展开说说。
核心观点：政务 RESTful API 不是学术标准，而是业务与技术之间的契约。每个原则都要先问一句：“这个场景真的需要这么严谨吗？”
1. 资源设计：别把“动作”塞进 URL
RESTful 的核心是资源。政务系统里最常见的错误是什么？直接把操作挂到 URL 上，比如 /api/getUserById、/api/approveApplication。嗯，我早期也这么干过。直到有一次做一个审批接口，前端直接传 action=approve，后端到处是 if-else，维护起来简直要命。
后来我强制团队遵守一个简单规则：URL 里只出现名词，动词交给 HTTP 方法。比如：
GET /applications— 获取申请列表POST /applications— 创建新申请PUT /applications/{id}— 更新申请（全量）PATCH /applications/{id}— 部分更新（如审批意见）
政务场景下资源还有层级关系。比如“某部门下的用户”：/orgs/{orgId}/users，别设计成 /users?orgId=xxx。前者更直观，也更符合 RESTful 的层级语义。
我的经验：资源命名用复数名词，层级不超过三级。超过三级可以考虑扁平化或查询参数。有一次遇到五级嵌套，接口路径长得像香肠，后来果断砍成两级加参数。
2. 统一接口：方法和状态码要“说人话”
这一条在政务项目里尤其容易走样。我见过不少系统，不管成功失败都返回 200，然后在 body 里放一个 code: "0" 或 code: "-1"。这样搞，调用方每次都得先解析 body，再决定下一步。想想看，如果直接用 HTTP 状态码，很多问题一下就清晰了：
| HTTP 方法 | 政务典型用途 | 安全/幂等 |
|---|---|---|
| GET | 查询数据（列表、详情） | 安全、幂等 |
| POST | 创建记录（提交申请） | 不安全、不幂等 |
| PUT | 全量更新（修改基础信息） | 不安全、幂等 |
| PATCH | 部分更新（审批状态） | 不安全、不幂等（需谨慎） |
| DELETE | 删除资源（逻辑删优先） | 不安全、幂等 |
状态码也要用得精准。我曾经在一个项目中排查问题，发现所有错误都返回 400，导致前端无法区分是参数格式错还是权限不足。后来我们约定：
- 200 — 请求成功
- 201 — 创建成功
- 204 — 删除成功（无内容）
- 400 — 请求参数错误
- 403 — 权限不足（不是 401，401 是未认证）
- 422 — 业务校验失败（比如身份证号不合法）
- 500 — 服务端内部错误
注意：政务系统常涉及敏感操作，比如“审批”、“驳回”。对于这类动作，我建议用 PATCH 并带上状态字段，不要用 POST /applications/approve 这种非 RESTful 的方式。我曾经接手过一个项目，所有审批都用 POST 到同一个 URL，全靠参数区分动作，后期加新动作时改动面非常大。
3. 无状态：政务的“会话”怎么处理？
RESTful 要求服务端不保存客户端状态。但政务系统几乎都有登录和权限，怎么做到无状态？答案就是。每次请求携带认证信息，服务端不依赖 Session。
我自己常用 JWT（JSON Web ），里面存用户 ID、角色、过期时间。政务场景有个坑——JWT 一旦签发，无法在过期前主动失效（除非用黑名单，但那又引入了状态）。解决办法是短有效期 + 刷新令牌。比如 access_ 15 分钟，refresh_ 7 天。
还有一个容易被忽略的点：审计日志。无状态意味着每次请求都要带上操作人、来源 IP 等上下文。我见过有人把这些信息存在服务端 ThreadLocal 里，结果集群部署时上下文丢失，日志对不上。后来我们统一在网关层把用户信息注入请求头，下游服务直接从请求头读取，这才彻底解决。
关键：无状态不是“没有状态”，而是“状态由客户端保管”。政务项目里，数据安全要求高，不要在 URL 里传明文 ，要用 Authorization: Bearer <> 头。
4. 可缓存：哪些数据能缓？哪些不能？
缓存能大幅提升性能，但政务数据很多涉及隐私和准确性问题。比如“每个月的低保发放名单”，如果缓存了昨天的数据，今天有人补发，界面就显示错误。所以敏感数据默认不缓存，只有明确标识为非敏感且更新频率低的才缓存。
通常我会用 Cache-Control: no-store 覆盖大部分接口，然后对字典、代码表、省份列表等静态数据设置 max-age=3600。Etag 也很好用，可以避免重复传输相同数据。我有个经验：不是所有 GET 请求都能缓存。比如 GET /applications/{id} 这种详情接口，如果业务要求实时查询，就别缓存。
避坑提示：我曾经把一个审批列表接口加了 30 秒缓存，结果审批员操作后刷新页面，列表还是旧数据，被用户投诉。后来所有涉及“待办”的列表一律不缓存。
5. 分层系统：网关与微服务的配合
政务系统现在大多采用微服务架构，API 网关做统一入口。分层的好处很明显：网关负责认证、限流、日志；服务层专注业务；数据层隔离不同数据库。但分层也容易出问题——调用链太长，性能下降。
我建议在网关层做请求合并。比如前端需要“申请人信息 + 申请条款 + 附件列表”，如果三个服务分开调，客户端要发三次请求。网关层做一个聚合接口，内部并行调用，再合并返回。不过要注意：聚合接口本身也要遵循 RESTful 原则，不要做成万能查询。
还有一个常见坑：跨层参数透传。比如分页参数 page、size 必须从网关传到服务层，有些团队在网关层自己处理了分页，导致服务层拿不到全量数据。保持各层职责清晰就好。
我的原则：网关只做“横切关注点”（安全、限流、审计），不替代服务层的业务逻辑。否则一旦需要调整业务，网关也要改，耦合度飙升。
小结
政务场景下的 RESTful 设计，说白了就是在规范与实用之间找平衡。上面这五个原则（资源设计、统一接口、无状态、可缓存、分层系统）是我在十几个政务项目里一点点磨出来的。别死抠标准，但核心思想不能丢——让接口直观、稳定、易维护。接下来你在设计新接口时，不妨用这五点对照一下，很多问题可能就提前暴露了。