接口设计：从前端开发的角度谈一谈接口规范
内容提要
文章从前端视角讨论接口设计。基本格式上，key应语义化、统一命名风格、正确使用复数与动词、避免重复；value应按场景选用字符串、数字、布尔、数组、对象或空值。业务格式上，相同结构数据应统一字段以便复用；状态码只用于前端无法判断的错误，并同时返回提示信息，文案由接口返回更灵活，状态码也可用关键词表达。
延伸解读
命名规范是降低对接成本的关键
文章强调 key 应语义化、统一命名风格，并正确使用复数与动词。这看似细节，却直接影响前端理解接口的速度。临时活动接口常因赶工期忽略命名，导致前端需反复沟通或写冗余代码适配。统一规范后，即使缺少文档，前端也能从字段名推断用途，减少对接摩擦。
数据类型选择影响前端判断逻辑
文章指出 value 应按场景选用字符串、数字、布尔、数组、对象或空值。特别提醒布尔值误返回字符串 'false' 会从假变真，引发逻辑错误。空值处理需前后端提前约定：返回 null、不返回字段或返回类型默认空值，三种方案各有适用场景，约定不清易导致前端判断遗漏。
相同结构数据应统一字段以利复用
不同页面常包含相同结构的数据，如新闻列表。文章建议这类模块统一字段名和数据结构，再按页面添加特色数据。这样前端可将新闻列表封装为公共方法，降低维护认知成本，减少重复代码和差错。若各接口字段随意变化，前端需为每个页面单独适配，复用性大打折扣。
状态码应克制使用并附带提示文案
文章主张状态码只用于前端无法判断的错误，如分类 id 是否存在；页码错误等常识性问题可由前端自行判断。同时建议返回 code 时一并返回 message，前端直接展示服务端文案，修改提示无需改页面。状态码也可用关键词表达，如 Discuz 的 keyword 方式，便于识别且避免数字重复。
Q&A
接口设计时，key的命名有哪些规范要求？
key应语义化，使用下划线或驼峰命名法并保持统一；包含多个结果时用名词复数（如tags）或名词+list（如memberList）；判断查询类字段用is/has/can等动词；使用合理缩写（如lv、msg）；避免同一层级重复key，不同层级也尽量不重复。
接口返回value时，如何选择合适的数据类型？
字符串用于文本、URL、图片地址等；数字用于时间戳、uid、年龄、价格等单一数值；布尔值用于判断条件（如isLogined）；数组用于返回多个同类型结果；对象用于聚合多个相关字段；null用于表示字段缺失，但需前后端约定处理方案（返回null、不返回字段或返回类型默认空值）。
为什么不同接口中相同结构的数据应该统一字段？
因为不同页面可能包含相同结构的数据（如新闻列表），统一字段名和数据结构能降低维护和对接成本，前端可以封装公共方法处理数据，减少差错，提高代码复用性。
什么情况下接口需要返回业务状态码？
只在前端完全无法识别的错误场景下才需要返回状态码，例如分类id不存在。前端能基于常识判断的错误（如页码错误导致列表为空）应由前端处理，无需接口反馈状态码。
接口返回错误时，为什么建议同时返回message？
同时返回message可以让前端直接使用服务端返回的文案进行提示，修改文案或新增状态码时无需修改前端代码，提高灵活性和容错率。
状态码一定要用数字吗？有没有其他表达方式？
不一定。可以用英文关键词（keyword）来表达状态码，例如Discuz的mobile API使用messageval如'word_banned'，这样看到文案就能知道错误类型，避免数字重复且便于理解。
