第一章 REST API 基础

讲加解密改造之前，咱得先把地基打牢。REST API 是啥，HTTP 方法怎么用，状态码怎么认，资源怎么设计——这些要是没理清楚，加解密加在哪都可能出问题。

我刚开始做接口时，也犯过糊涂。觉得「RESTful」就是个时髦名词，用 POST 搞定一切就行。直到被老架构师骂了一顿，才老老实实回头补课。

1.1 什么是 RESTful？

REST 全称是 Representational State Transfer，翻译过来叫「表述性状态转移」。听着绕口，说白了就是一套设计 Web API 的指导原则。

它的核心思想其实很简单：

• 资源（Resource）是一切的基础。用户、订单、文章，都是资源
• 表现层（Representation）是资源的展现形式。JSON、XML、HTML，都行
• 状态转移（State Transfer）靠 HTTP 方法驱动。增删改查，各司其职

RESTful 架构有六个约束条件，我列个表方便你记：

约束条件	说明	我的体会
客户端-服务端	分离关注点，两端独立演进	加解密改造时，改服务端不影响客户端
无状态	每个请求包含全部信息	鉴权 放请求头，别依赖 session
可缓存	响应需明示是否可缓存	Cache-Control 设不对，加解密后缓存会乱
统一接口	标准方法操作资源	这才是 REST 的精华
分层系统	中间层可加代理、网关	加解密网关就放在这一层
按需代码（可选）	服务端可传可执行代码	实践中极少用

1.2 HTTP 方法

HTTP 方法就是操作资源的「动词」。RESTful 接口里，每个方法有明确的语义和用途。

我见过有人把所有操作都写成 POST，理由竟然是「好写」。嗯，这种接口对接起来真要命。你想想看，连查个数据都要看文档才知道用哪个接口，多累啊。

方法	用途	是否幂等	是否安全
GET	获取资源	是	是
POST	创建资源	否	否
PUT	更新资源（全量）	是	否
PATCH	更新资源（部分）	否	否
DELETE	删除资源	是	否
HEAD	获取响应头	是	是
OPTIONS	查看支持方法	是	是

幂等性很重要，尤其在加解密场景下。如果请求因为解密失败需要重放，幂等方法保证重放不会破坏数据。

1.3 状态码

状态码是服务端给客户端的「回话」。选对了状态码，对接双方能省不少沟通成本。

我自己的习惯是：200 和 201 用得最多，4xx 必须明确告诉调用方错在哪，5xx 要配合日志排查。切记不要全部返回 200 然后在 body 里放错误信息——这就像打电话接起来说「喂」，然后一直不说正事。

分类	范围	常见状态码	含义
信息	1xx	100 Continue, 101 Switching Protocols	协议级别的中间响应，普通 API 少见
成功	2xx	200 OK, 201 Created, 204 No Content	请求被正确接收并处理
重定向	3xx	301 Moved Permanently, 304 Not Modified	资源地址变了，客户端需重新请求
客户端错误	4xx	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests	请求本身有问题，客户端得改
服务端错误	5xx	500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable	服务端有故障，客户端可稍后重试

让我用一个实际场景帮你理解：有一次我在对接银行接口，签名过期后对方返回 200 和「验签失败」。我写了重试逻辑，结果反复扣钱。后来改成严格按状态码办，才算稳住。

1.4 资源设计原则

资源怎么设计，直接影响接口的可读性和加解密的实现成本。我总结了四个核心原则，每个都踩过坑：

1. 用名词，不用动词
   /users 里操作用户，而不是 /getUsers 或 /createUser。方法已经暗示了动作
2. 用复数表示资源集合
   /orders 表示订单列表，/orders/123 表示单个订单。别写 /order/123
3. 用层次表示从属关系
   /users/456/orders/789 表示用户 456 下的订单 789。别用查询参数拼关系
4. 用查询参数做过滤和分页
   /orders?status=paid&page=1&size=20。别在路径里写 /orders/page/1/size/20

为什么资源设计对加解密改造重要？你想啊，如果资源路径乱七八糟，加解密规则就没法统一管理。比如 /api/v1/users/profile 和 /api/v1/getUserProfile，你能用一套规则覆盖吗？不可能。

我个人推荐的做法是：先定好资源树，再定加解密范围。哪些资源需要加密，哪些资源可以明文，一目了然。

好了，我们把这一章的核心知识结构画成一张图，方便你整体把握：

这张图把本章四个核心模块串起来了。记住，RESTful 约束是骨架，HTTP 方法是动作，状态码是反馈，资源设计是蓝图。四者缺一不可。