接口规范细节问题【JSON格式】.docx

软件开发接口文档问题软件开发过程中，后台接口不规范导致的问题总结，现在后台接口规范应该学习restful 风格，具体参考网上资料1.文档存放问题目前存放是这种状态：1.1 文档杂乱分不清哪些是不用的接口，哪些是正在用的接口，哪些是更新后的接口1.2 接口查询效率慢word格式管理，不方面查询1.3 多个word文件，下载操作麻烦每次查看接口，需要下载word，不能避免下载操作查看，效率不高文档分工问题2.1 接口文档的编写后台统一提供接口，没有考虑到数据解析的便利性，客户端解析带来一定的不可避免的性能，逻辑方面的费时【例如排序问题耗费性能】，不利于最终客户的体验；2.2 接口返回格式定义的问题需要解决后台接口开发人员负责编写3.文档格式问题3.1 接口返回体问题3.1.1 json字符串未转义问题无特殊需求 尽量不要返回如此需要转义的接口格式3.1.2 没有特殊需求，json格式必须有key没有key的返回体，客户端需要做大量判断处理，而且易读性非常差，解析数据，容易产生错误，不符合规范3.1.3 json格式的对象，数组不能轻易变更列表有数据的时候：列表没有数据的时候：3.1.4 json格式之 数组 最好不要写成如下格式 [1,2,3,4 ]3.1.5 json数组 分组 排序问题按照组名字段排序，分组问题，客户端需要做额外的处理【涉及到额外的循环耗时】3.1.6 json格式返回移动端不需要的格式，字段以及无用数据3.1.7 json对象具体字段数据类型不要变动3.2 接口统一异常提示问题客户端开发人员的“尴尬”：面对如下的异常问题，客户端不知道该返回给 客户 看什么？直接提示 “程序错误” 不好，客户端开发人员直接固定返回错误提示 “系统错误”也不好，相当于接口返回体没有起到应有的作用；例如输入表单的时候，输入格式不对，后台无法保存的时候，不能一概提示 程序错误！！！建议而是根据客户端传递给服务端的指定参数，通过判断参数的方式，来检查是哪一个环节产生了问题，然后具体通过接口返回体的方式，返回给客户端【核心原则，接口提供方给接口使用方更人性化的提示信息】，最终面对的都是客户，不能让客户知道不友好的提示。a： 不友好的提示： b:友好的提示：3.3 接口参数问题3.3.1 多余参数问题例如 接口实用参数只有 param1 但是接口需要传递 另外的参数 parm23.3.2 参数类型文档说明问题3.3.2.1 方法类型指定 get方法，post方法等3.3.2.2 参数类型指定 form表单参数，json参数等