RPC风格API迁移到RESTful不是重写接口，而是重构资源建模和请求语义：需对齐HTTP方法、URI设计与状态码语义，核心是将动作导向（如/action=createUser）转为资源导向（如GET /users/123），并严格遵循REST统一接口原则。
直接说结论：RPC 风格 API 迁移到 RESTful 不是重写接口，而是重构资源建模和请求语义——关键在 HTTP 方法、URI 设计 和 状态码语义 的对齐，而非单纯改路由或加 GET/POST 判断。
怎么识别当前是 RPC 风格？
典型表现是接口路径不体现资源，而体现动作，且严重依赖 action 参数或单一路由兜底：
-
/api/v1/index.php?action=createUser或/api/v1/call?method=user.delete - 所有请求走
POST，靠 body 里的method字段区分增删改查 - 返回结构固定为
{"code":0,"data":{...}}，不随 HTTP 状态码变化 - 没有
Content-Type: application/json显式声明，或忽略Accept头
URI 和动词如何对应 RESTful 资源操作？
迁移不是把 action=getUserById 改成 /user/123 就完事，得先定义资源边界。常见错误是把业务动作当资源（如 /user/changePassword），正确做法是把密码视为用户资源的可更新属性：
-
GET /users→ 列表（替代getUserList） -
GET /users/123→ 单个用户（替代getUserById?id=123） -
POST /users→ 创建（替代createUser），body 含完整用户数据 -
PATCH /users/123→ 局部更新（如改邮箱、头像），body 只含变更字段 -
DELETE /users/123→ 删除（替代deleteUser?id=123） - 密码重置应走
POST /users/123/password-reset-requests（新建一个“重置请求”子资源），而非PUT /users/123/password
PHP 实现时最容易踩的坑
用原生 PHP 或 Slim/Laravel 等框架都绕不开这几个点：
立即学习“PHP免费学习笔记（深入）”；
- 忽略
$_SERVER['REQUEST_METHOD']直接读$_POST，导致PATCH/DELETE请求体为空——需手动解析php://input - 用
http_response_code(200)硬编码成功状态，掩盖实际失败；应根据逻辑返回201 Created、404 Not Found、422 Unprocessable Entity等 - 把所有错误统一返回
500，丢失客户端区分能力；比如参数校验失败该用400 Bad Request，权限不足用403 Forbidden - 没处理
OPTIONS预检请求，导致前端跨域调用PATCH/DELETE失败——至少要返回Access-Control-Allow-Methods - 路由配置未启用严格模式，
/users/123/和/users/123被当成不同路径，引发缓存或代理问题
要不要兼容旧 RPC 接口？
上线初期建议双写并行，但必须明确下线时间表：
- 新 RESTful 接口加版本前缀（如
/v2/users），旧 RPC 接口标记为Deprecated响应头 - 日志中记录旧接口调用方 IP 和 User-Agent，定向推动迁移
- 绝不做“RESTful 外壳 + RPC 内核”——例如
GET /v2/users/123内部仍调用callRpc('getUserById', ['id'=>123])，这会丧失缓存、幂等性、语义清晰等全部收益
真正难的不是写几个新路由，而是让团队所有人理解：URI 是名词，HTTP 方法是动词，状态码是结果——三者共同构成契约。一旦开始混用（比如用 GET 触发删除），后续就只能不断打补丁。
