别让字段名成为沟通障碍
开发一个接口时，很多人只关注功能能不能实现，却忽略了字段命名带来的长期影响。比如你返回一个字段叫 status，值是 1 或 0，前端同事拿到后得翻文档才知道 1 是“已通过”还是“待审核”。如果换成 approval_status，再配合枚举说明，理解成本立马下降。
字段命名不是写给自己看的日记，而是团队协作的语言。尤其在跨部门对接时，清晰的命名能减少大量来回确认的时间。
使用一致的命名风格
项目里有人用下划线 user_name，有人用驼峰 userName，调用方就得时刻记住不同接口的风格差异。建议在团队内统一规范，比如对外 API 全部使用蛇形命名（snake_case），内部服务可用驼峰。只要统一，就不容易出错。
特别是布尔类型的字段，避免使用 is_active 这种带歧义的名称。比如用户被冻结了是不是就 is_active=false？但如果是休眠账户呢？建议结合场景细化，比如 account_status 配合字符串枚举：active、frozen、pending 等。
避免缩写和模糊表达
别为了省几个字母写 usr_type 或 reg_tm。第一次见的人根本反应不过来。全拼又不费劲，user_type 和 registration_time 清清楚楚。别高估别人的脑补能力。
还有像 data 这种万金油名字也尽量少用。比如返回订单详情时，别直接给个 data: { ... }，换成 order_detail 或 order_info 更明确。
时间字段要标明单位和时区
时间是最容易踩坑的类型之一。字段名叫 create_time 没问题，但一定要在文档里说明是秒还是毫秒。前端 JS 处理毫秒，后端有时候习惯传秒，一不小心页面就差了八千年。
更稳妥的做法是在命名上体现单位，比如 created_at_ms 表示毫秒级时间戳。涉及跨地区业务的，还要考虑是否带时区。直接用 created_at_utc 比让对方猜强得多。
{
"user_id": 1001,
"user_name": "zhangsan",
"account_status": "active",
"login_count": 23,
"last_login_at_ms": 1717056000000
}这个例子中每个字段都自解释性强，调用方基本不用查文档就能猜出含义。
复数与单数要分清
返回列表数据时，外层字段别用 data 包着一堆东西。改成 users 或 order_list 能立刻知道这是集合。如果是单个资源，就用单数形式，比如 user 而不是 userList。语义准确才能减少误解。
嵌套结构也一样。别在用户信息里加个 roles 字段，结果里面只有一个字符串。要是只返回一个角色，就叫 primary_role 或 current_role，别滥用复数形式误导别人。