为什么 REST API 离不开 JSON，以及那些被忽略的优化点

JsonTool
订阅
充电
|

我第一次写 API 的时候，还挺兴奋。GET /api/v1/users/123 一敲，浏览器里能吐出一段 JSON，就觉得自己很厉害。

可过几天自己调试的时候，心态就崩了：字段命名一会儿驼峰一会儿下划线，报错只给一句“Invalid”，接口动不动就塞我一坨几十 KB 的 JSON。那感觉，就像点了份盖饭，打开盖子发现饭和菜全糊一起了，还加了不该放的辣椒。

慢慢踩坑之后，我才开始琢磨：JSON 虽然只是个格式，但写法和习惯，真能把一个 API 从“凑合能用”变成“舒服好用”。

字段别乱来

我见过最魔幻的接口：userName 和 user_id 出现在同一个 JSON 里。前端的小伙伴吐槽过：“这到底要我用 user.name 还是 user_name 啊？”

其实定好一个风格就行，要么全驼峰 camelCase，要么全下划线 snake_case。比如：

1
2
3
4
{
  "user_id": 123,
  "user_name": "Alice"
}

起码眼睛扫过去不会乱，写查询的时候也不用揣测对方的习惯。

报错别只丢一句话

最怕遇到这种返回：

1
"Invalid user id"

前端同事立刻皱眉头：“那到底是用户没注册，还是我传参写错了？”

更靠谱的写法应该长这样：

1
2
3
4
5
6
7
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User id does not exist",
    "hint": "Check if the user is already registered"
  }
}

多一点结构化信息，前端能根据 code 来做逻辑，后端排查也能更快。不然就像你只听见“错了”，却完全不知道错哪儿。

别把数据库整锅端上来

有些人写接口特别“佛系”：查出来什么，就全返回。于是返回的 JSON 一看几百行，其中还有 password_hash、last_login_ip 这种根本不该暴露的字段。

1
2
3
4
5
6
7
8
9
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "password_hash": "$2a$10$abc...",
  "last_login_ip": "192.168.0.1",
  "created_at": "2025-08-20T12:30:00Z",
  "updated_at": "2025-08-21T09:10:00Z"
}

调试时你会发现：传输慢，解析费劲，还得担心安全问题。
其实绝大部分场景只要返回核心字段，其他的按需拉取就好：

1
GET /api/v1/users/123?fields=id,name,email

这样前端能自选要啥，不必抱着大礼包回去拆。

列表要带上下文

返回数组的时候，很多接口直接给一串对象：

1
2
3
4
[
  { "id": 1, "title": "Post A" },
  { "id": 2, "title": "Post B" }
]

乍一看没毛病，但总条数呢？分页信息呢？前端要么另写请求，要么只能猜。

更贴心的写法是：

1
2
3
4
5
6
7
{
  "total": 42,
  "items": [
    { "id": 1, "title": "Post A" },
    { "id": 2, "title": "Post B" }
  ]
}

有了 total，接口才算完整。

时间和数字别乱整

我碰到过一个“神奇”接口：价格字段返回 "19.99"（字符串），前端拿去加减直接报错。还有接口给我一个毫秒时间戳，我还得自己转。

经验是：

  • 时间统一用 ISO 8601："2025-08-21T09:10:00Z"，人和机器都能认。
  • 数字就该是数字："price": 19.99，别加引号。

小细节，但能少掉一堆 bug。

收个尾

API 和 JSON 就像饭和筷子，天天用，但到底顺不顺手，全看有没有在意那些小细节。字段统一、报错结构化、返回精简、数组带上下文、时间数字规范——这几个习惯养起来，一个接口就会让人舒服很多。

我自己改掉这些小毛病之后，调试 API 的时候，心态真是好太多了。