接口开发文档说明

原创

已于 2025-02-19 09:47:42 修改 · 1.1k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java #javascript #json

于 2022-06-21 16:32:37 首次发布

这篇博客介绍了API接口的设计规范，包括路由模式、接口类型、数据提交方式、控制器方法命名、以及数据返回字段的格式和详细说明。重点强调了数据返回统一使用JSON格式，包含status、info和data三个字段，对status字段的值进行了详细解释，并给出了data字段的三种数据格式。

路由定义:
框架使用多应用, 默认路由模式; url三部分组成, 格式为: /模块名称/控制器名称/方法名称;
如 /core/Config/lists: 即为平台核心模块/config控制器/lists方法.
接口请求分类:
接口分为两种类型: 命令型和获取数据型;
命令型接口如添删改接口, 这种接口data字段一般为空数组;
获取数据型如查询接口, 这种接口status值总是1, info字段只是给前端开发人员做个提示, 数据到底是否获取成功, 需要再判断data的值是否为空数组;
数据提交方式:
框架使用最宽泛的方式, 支持所有的提交方式, 并且不做提交方法的判断. 请求到底是要干什么, 不是根据请求方式进行判断, 而是使用方法名进行判断.
一般情况在后端开发调试过程中, 直接使用GET方式在URL中传参更加方便; 对于前端开发人员, 使用POST和GET方式都可以, 根据实际情况, 以快捷方便为原则进行选择即可(但是在一定程度上要统一, 要封装, 建议全部使用POST);
特殊情况, 比仿说要传递大量数据的, 如text字段/文章正文内容/文件上传等, 酌情处理(POST);
常用控制器方法命名规范:
1. 添加/保存: edit
2. 查询单条数据: detail
3. 分页列表: lists
4. 删除: del
5. 不分页列表: ls (注意, 当表内数据过多, 比仿说超过50条时谨慎使用, 因为此方法是返回表内所有的数据)
6. 查询前20条列表: search
数据返回字段格式:
数据返回统一使用JSON格式. 所有接口都包含三个字段. [‘status' : ‘int 状态码’, 'info' : ‘string 信息说明’, 'data' : ‘array/array object