接口字段命名看着是小事，实际影响后面所有对接。命名一乱，前端猜、第三方猜，文档写十遍也讲不清。命名一乱，代价有多大？
命名要统一，不要有创意
同一份数据，一个接口叫 userName，另一个叫 user_name，前端就得记两套。我们接手过一个项目，三种写法并存，还夹着拼音缩写，看着头疼。定一条规则就够了：要么全驼峰，要么全下划线，全项目不例外。缩写也别自创，用行业通用的，剩下的写全拼。规则定下来之后，新接口照着写就行。
时间格式更要统一。有的返回时间戳，有的返回字符串，还有的带时区有的不带。前端拿到之后要写三套解析，出错概率成倍上升。我们一般统一成带时区的标准格式，前端直接格式化显示。金额也一样：单位是元还是分，有没有小数，必须写清楚。我们见过单位搞错导致多收一百倍的，上线才发现。这算不算隐性成本？
错误码要能看出问题
出错的时候只返回操作失败，前端只能弹个通用提示，用户不知道该改什么。好的做法是给每个可预期的错误一个码和一句人话。前端按码处理。我们习惯把校验失败细化到字段，告诉用户是哪一项不合规。这样用户改一次就能过，不用反复试。错误码不要随便改，改了就等于让所有对接方跟着改。
还有一点：返回结构要稳定。列表就固定是数组加总数。别这个接口有下一页那个没有。前端封装一次就能通用，不用每个接口写一套判断。我们做接口时会把分页、排序与筛选参数统一，第三方接入时也省得问。这些约定写在文档开头，比散落在各接口下面有用。文档写好了，答疑量能少一半。
版本和兼容
接口一上线就有人用，改字段等于破坏承诺。真要改，加字段可以，删字段要谨慎，最好保留一段时间并标注废弃。我们一般用版本号区分，老版本留着跑。新业务走新版。迁移要给缓冲期，提前通知对接方。别今天说下周就停。见过直接改名上线的，第三方的系统全挂，连夜回滚。
接口设计常见疑问
接口字段命名怎么定
全项目统一用驼峰或下划线其中一种，缩写采用行业通用写法，其余写全拼，不做个性化命名。
时间和金额怎么返回
时间统一为带时区的标准格式，金额明确单位与小数位，避免前端重复解析与单位误解。
改字段要注意什么
加字段优先、删字段谨慎并标注废弃，用版本区分新旧，迁移须提前通知并留缓冲期。
总结：接口设计的功夫在约定：命名统一以及时间金额写清跟错误码细化和结构稳定与改字段留缓冲。