如何设计一个 RESTful API

核心原则是「以资源为中心，用 HTTP 方法表达动作」，具体规范如下：

表格

设计要点	规范示例	说明
URL 用名词复数	`/users`、`/orders`	避免 `/getUser`、`/addOrder` 这种带动作的 URL
HTTP 方法对应操作	`GET /users/1`	获取 ID 为 1 的用户
	`POST /users`	创建新用户
	`PUT /users/1`	全量更新用户 1
	`PATCH /users/1`	部分更新用户 1（如只改手机号）
	`DELETE /users/1`	删除用户 1
状态码语义化	200（成功）、201（创建成功）	400（参数错误）、401（未授权）、404（资源不存在）、500（服务器错误）
版本控制	`/api/v1/users`	方便后续迭代兼容
过滤 / 分页 / 排序	`/orders?page=1&size=10&sort=createTime`	通过 URL 参数实现，不污染资源路径
统一返回格式	`{ "code": 200, "data": {}, "message": "success" }`	前后端约定统一结构，便于处理

这是微服务 / 分布式架构中两种主流的通信方式，核心差异在设计思想、协议和适用场景：

表格

对比维度	RESTful	RPC
核心思想	面向资源，通过 HTTP 方法操作资源	面向方法 / 服务，像调用本地函数一样调用远程服务
常用协议	HTTP/1.1/2，基于 JSON/XML	自定义协议（如 Dubbo）或 HTTP/2（如 gRPC，基于 Protobuf）
数据格式	JSON/XML（文本格式，可读性好）	Protobuf/Thrift（二进制格式，体积小、序列化快）
性能	相对较低（HTTP 头部大、文本解析慢）	高（二进制协议 + 长连接，适合高频调用）
适用场景	前后端分离、第三方开放 API、跨平台调用	微服务内部调用、高并发 / 高性能场景（如金融核心服务）
典型框架	Spring MVC、Express.js	Dubbo、gRPC、Thrift

一句话总结：RESTful 更适合对外公开、跨语言的接口；RPC 更适合服务间内部通信，追求极致性能。

可以从「认证、授权、传输、防攻击」四个维度来做：

身份认证
- Token 认证：JWT（JSON Web Token），登录后返回 Token，后续请求放在 Header（Authorization: Bearer xxx）中
- OAuth2.0：第三方授权场景（如微信 / 支付宝登录）
- API Key：开放平台接口，客户端用 Key 做身份标识
权限控制（授权）
- 基于角色（RBAC）：不同用户角色（管理员 / 普通用户）分配不同接口权限
- 基于资源：控制用户能访问哪些数据（如用户只能修改自己的信息）
传输安全
- 强制使用 HTTPS，加密传输数据，防止中间人窃听和篡改
- 敏感数据（如密码、身份证号）禁止明文传输，后端存储也要加盐哈希
防攻击手段
- 防 SQL 注入 / XSS：参数校验、ORM 框架、输入转义
- 防 CSRF：请求携带 CSRF Token，或 SameSite Cookie 策略
- 限流防刷：限制单个 IP / 用户的请求频率（如 1 分钟最多 100 次），防止 DoS 攻击
- 防重放：请求中加入时间戳 / 随机数，服务端校验请求是否过期或重复
- 敏感操作日志：记录关键接口（如转账、删除）的请求信息，便于审计排查