开发webapi程序时需要考虑的细节汇总

Posted 2022-12-09 三五月儿

1、根据api接口访问路径定义好controller和action。
2、记录操作日志。包含接口入参、出参、异常以及重要的节点数据（数据库返回、第三方接口返回、重要的私有变量值）
3、入参合法性检查。非空检查。需要校验身份证、邮箱、手机号、网址等值。
4、定义好接口的返回状态和消息。建议0表示成功，非0表示失败，且不同的状态值必须区分好。
可包括数据库操作、第三方接口调用、入参校验、程序异常、成功等分类。
5、选择合适的HTTP操作，get还是post需要根据场景进行选择。
6、参数传递方式确定，get还是post还是request请求头。
7、定义好接口出入参实体。对于返回值建议包含status（状态）、msg（消息）、data（数据）等字段，没返回数据时，data取值null。
8、考虑返回数据是否需要排序、分页等操作。
9、对于返回列表的数据需要考虑好没数据时是返回错误还是返回空集合，但是接口返回成功。
10、避免由于判断分支过多导致if-else嵌套过深，在非法的条件下进行return。
11、多层嵌套if-else时，保持判断逻辑的一致性，所有条件都判真，或者都判非。
12、确定客户端cookie管理方案。是签名Cookie还是令牌Cookie。
13、确定是实现同步接口还是异步接口。
14、确认图片文件的传输方式。是base64还是文件流还是multipart。
15、引入异常重试机制。比如调用第三方接扣、数据库调用等。
16、确定异常的处理方式。api不要抛出异常，内部方法可以抛出异常，在api层捕获处理。
17、活用ActionFilterAttribute进行日志记录等操作。
18、接口返回字段均为小写或者大写。避免命名混乱导致的BUG。
19、统一接口出入参中时间格式。