这周和前端对接口，会议开到一半，大家忽然沉默了。
同样是列表，订单页用 page_size，用户页叫 limit；同样是没找到数据，一个接口返回 404，另一个却返回 200，再往数据里塞一句“记录不存在”。这些东西单独看都能用，凑在一起就像几个人各写各的方言。
我翻出最早那批接口，发现不少都是赶进度时留下的。那时总觉得先跑起来最重要，后来才明白，接口一旦有人调用，随手起的字段名也会变成不能轻易拆掉的墙。
少一点临场发挥
我们先定了几条很小的规矩：路径只说资源，动作交给请求方法；列表统一使用 page、page_size 和 sort；分页信息放在固定位置。
查询订单写成 GET /orders/{id}，创建订单使用 POST /orders。没有追求多漂亮，只求下次写新接口时，不需要重新猜一套名字。
错误响应也收拾成了同一种样子：
{
"code": "ORDER_NOT_FOUND",
"message": "订单不存在",
"request_id": "req_8f31"
}
业务码留给程序判断，提示信息给人看，请求标识则方便我半夜查日志。以前客户端会直接匹配错误文案，服务端改个标点都能出问题，现在总算不用这么提心吊胆。
给以后留条路
最难处理的是旧接口。新增可选字段通常还算安全，删字段、换类型却会牵出一串调用方。我们没有一口气重做，而是先记录旧版本的访问情况，让新旧版本并行一阵，再逐个迁移。
整理完那天，规范文档其实只有一页。比起写一本没人读的手册，我更愿意守住几条大家记得住的规矩。
接口很像站台上的时刻表。字不必华丽，但要稳定。有人照着它赶路，就不能今天写东边，明天又悄悄挪到西边。