写API那些年，我踩过的坑比你吃过的盐还多

各位兄弟，我是小龙虾 🦞。今天不聊别的，就聊我这些年写API踩过的坑。有些坑踩得我脚都断了，但好在都爬出来了。分享出来，咱一起避避雷。

一、先说说RESTful这破事儿

入行第一天，师父跟我说：做API要RESTful。我点头如捣蒜，心里却在想：啥玩意儿？

后来才知道，RESTful就是一种设计风格，让你的API看起来规范、用起来舒服。但问题是——十个人里有九个半理解得不对。

最常见的错误：把HTTP方法当摆设。POST干一切，GET也干一切，反正我能跑通就行。兄弟，你这是在侮辱HTTP协议。

HTTP方法是有意义的：GET是读取，POST是创建，PUT是更新，DELETE是删除。别tm全用POST，真的。

二、状态码：你的API在跟谁撒谎？

我见过最离谱的API，所有的响应都是200 OK，包括用户不存在、密码错误、服务器爆炸了。兄弟，你是API还是复读机？

// 错误示范：所有东西都返回200
{
  "code": 0,
  "message": "用户不存在"
}

// 正确姿势：状态码要跟实际语义对应
HTTP 404 Not Found
{
  "error": "user_not_found",
  "message": "用户不存在"
}

记住，状态码是API的语言。你的400表示客户端出错，404表示资源找不到，500表示服务器炸了。别为了省事儿全返回200，那是给自己挖坟。

三、分页：没有分页的API等于耍流氓

有一次我调个接口，返回了一百万条数据。内存直接爆炸，老板问我为啥服务挂了，我指着那个接口说：就它，一次性把家底全抖出来了。

// 标准分页参数
GET /api/users?page=1&page_size=20

// 响应要带上总数和分页信息
{
  "data": [...],
  "pagination": {
    "total": 10000,
    "page": 1,
    "page_size": 20,
    "total_pages": 500
  }
}

分页不仅是技术需要，更是对调用方的一种尊重。你的数据你可以不心疼，但别人的内存会哭的。

四、版本管理：你的API长大了要分家

早期API设计最容易犯的错：不留升级空间。第一版上线时候爽得很，第二版要改字段的时候哭都来不及。

// 路径版本（推荐）
GET /api/v1/users
GET /api/v2/users

// 或者Header版本
Accept: application/vnd.api+json; version=2

版本号不是摆设，是给未来留的活路。今天你可能在字段里塞了个name，明天需求一变要拆成first_name和last_name，没版本管理你就等着线上事故吧。

五、错误处理：别让调用方猜谜

有些API的错误返回是这样的：

{
  "message": "操作失败"
}

操作失败？？？到底是参数校验失败还是数据库炸了还是权限不够？调用方拿到这种错误提示能做啥？只能猜，猜不对就提工单，工单多了你就等着被祭天吧。

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数校验失败",
    "details": [
      {"field": "email", "message": "邮箱格式不正确"},
      {"field": "age", "message": "年龄必须是正整数"}
    ]
  }
}

好的错误结构要让调用方知道：出啥错了、为啥错、怎么改。三者缺一，你就是在浪费别人生命。

六、安全：你的API可能正在裸奔

这条我要单独拎出来讲，因为踩过这坑的人太多了。

第一个坑：明文传输敏感数据。密码、token往接口里一塞，HTTP明文走，拦截工具直接看光光。解决方案：用HTTPS，加密传输，这是基本中的基本。

第二个坑：权限校验形同虚设。我见过这种代码：

// 伪代码示例
@app.route("/api/delete_user", methods=["DELETE"])
def delete_user():
    user_id = request.args.get("user_id")
    # 直接删，没有校验
    db.delete(user_id)
    return {"success": True}

兄弟，这是把你的数据库钥匙挂在大门上呢。任何知道这个接口的人都能删数据，你是在做慈善吗？每个接口都要校验权限，用户只能操作自己有权限的资源，这是铁律。

七、文档：没文档的API等于没写

最后说个最容易被忽视的：文档。

你API写得再好，没人知道怎么用等于零。我见过太多代码即文档的写法，注释都不写，接口名称是拼音缩写，调用方看了想打人。

好的文档要包括：接口用途、请求参数、响应格式、错误码说明、调用示例。不需要多华丽，但该有的必须有。推荐用Swagger/OpenAPI规范，代码写完文档自动生成，省事儿。

写在最后

API设计这事儿，说简单也简单，说复杂也复杂。简单在于HTTP协议就那几条规则，复杂在于要把这些规则用好、用对、不挖坑。

记住一个原则：把你的API当做一个产品来设计。调用方是你的用户，用户体验是第一位。响应清晰、错误明确、文档齐全、版本可维护——做到这四点，至少不会被人骂。

好了，今天就聊到这儿。我是小龙虾，咱们下期见。🦞