1. 接口设计基础：RESTful 架构、HTTP 方法、状态码设计

接口设计，说白了就是让不同的系统能好好说话。在我十多年的从业经历里，见过太多因为接口设计不规范引发的线上事故。合规治理的第一步，就是把接口基础打扎实。

1.1 RESTful 架构：不只是 URL 风格

很多人觉得 RESTful 就是“把 URL 写成名词，用动词指代操作”。这个理解有点浅了。我个人习惯把 REST 理解成一种设计哲学，它要求我们以资源为中心来思考问题。

为什么一定要强调无状态？我年轻的时候在一个电商平台做过一个购物车接口，把用户数据保存在服务端 Session 里。结果每次部署新版本，所有用户的购物车都丢了。从那时起，我就强迫自己把状态全部推到客户端，服务端只管处理请求。

1.2 HTTP 方法：动词的正确用法

HTTP 协议定义了若干方法，但我们最常打交道的只有五个。你别看它们少，用错了照样出事。

关于幂等这件事，我补充两句。一个请求发出去，如果网络超时了，客户端重试以后后端应该能保证结果一致。GET、PUT、DELETE 天生支持幂等，但 POST 不行。如果你用 POST 去创建订单，你的客户端必须做好去重防护。

举个具体例子：

# 好的设计
GET    /api/v1/users/{id}       # 获取用户信息
POST   /api/v1/users             # 创建新用户
PUT    /api/v1/users/{id}        # 全量更新用户（传完整对象）
PATCH  /api/v1/users/{id}        # 部分更新（只传要改的字段）
DELETE /api/v1/users/{id}        # 删除用户

# 不好的设计（我对这种深恶痛绝）
GET    /api/v1/getUser?id=123
POST   /api/v1/createUser
POST   /api/v1/updateUser
POST   /api/v1/deleteUser

1.3 状态码设计：别只回 200 和 500

你想想看，状态码就是接口的方言。方言太乱，别人就听不懂你在说什么。很多团队只用了 200（成功）和 500（服务器异常），这等于没用心设计。

我建议把状态码分为三大类：

你以为光有状态码就够了吗？不够。我曾在一个金融项目中见过，4xx 写了 "参数错误" 但关键字段是空的——结果排障耗了三个小时。那段代码是我同事写的，但这次事件以后，我带头立了一个规范：所有 4xx 响应都要详细标注具体哪个字段错了、期望什么格式。

// 一个规范的错误响应体
{
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "请求参数校验不通过",
        "details": [
            {
                "field": "email",
                "reason": "格式无效，期望：user@example.com"
            }
        ]
    }
}

1.4 一张图看懂接口设计基础