前端规范文档

# api文档格式

# 简介

api文档是前后端分离开发的枢纽，各位同事应该严格遵守相关开发规范。规范书写文档会大大提高代码维护效率！！！

为了提高api文档质量，我们开发了一款文档工具来规范api文档录入 工具地址

# 文档构成

# 开发环境

推荐开发环境 沙盒环境 测试环境 生产环境

  1. 沙盒环境用于前端独立开发，部分场景下前端可脱离后端通过mock形式获取数据，文档工具提供完整mock能力。

  2. 测试环境可进行前后端联调，数据相对真实，可以较为完整模拟真实生产环境。

  3. 生产环境

# 返回状态码

实际开发过程中，我们不完全遵守http状态码相关规范对数据进行返回，对于 json 格式数据返回，http状态码为 2xx的都当作接口连通，http状态码非2xx的全部当作服务器异常。

// 常规数据返回格式
interface {
    code: number,
    msg: string,
    data: <array|object>
}
// 示例
{
    code: 0, //状态码
    msg: "操作成功", //操作信息
    data: {}, //业务数据
}
1
2
3
4
5
6
7
8
9
10
11
12

各类常见数据返回格式

下面是状态码示例，各项目可根据实际情况灵活改变状态码

0      代表正常请求

100x   代表参数相关错误
1001   代表缺少某些必填字段 或者 代表字段不缺少，但是字段类型不匹配
1002   代表参数不存在数据库中，例如：添加一个项目，需要填写项目类型，项目类型是一个枚举值，但是添加的时候查询不到该枚举值则报错
1003   代表参数在数据库中存在重复，例如：添加一个项目，需要填写项目名称，但是添加的时候查询到名称已经存在
1004   代表参数长度超长，例如：添加一个项目，需要填写项目名称(限制为10个字符)，超过长度不允许添加

400x   代表权限或者操作违法
4001   操作错误，用户有权操作但是参数或者某些别的原因导致此次操作不被允许，例如：用户在文件下面创建一个文件夹是不被允许的(只能在文件夹下面创建文件)

500x   代表内部错误
1
2
3
4
5
6
7
8
9
10
11
12

WARNING

切记不要用相同状态码代表不同含义错误！

切记不要将所有异常归结于一种状态码，这样会大大增大调试和后期维护成本！

# 版本管理

一个持续迭代的项目的文档应该是区分版本的，每一次大版本的升级或者重构都应该同时更新文档版本，文档版本管理会让文档更加的清晰。文档工具提供完整的版本管理功能。

# 完善的文档

文档可根据 文档工具 进行录入，工具对可用性和文档完善程度进行了代码层面的限制，可以大幅避免低质量文档被录入。

# 书写规范

# 驼峰命名

  1. json格式传输数据前后端都应该遵守驼峰命名规范

  2. 请求url遵守驼峰命名

http:127.0.0.1:8888/api/userInfo  //推荐
http:127.0.0.1:8888/api/userinfo  //不推荐
http:127.0.0.1:8888/api/user_info  //不推荐
http:127.0.0.1:8888/api/user-info  //不推荐
1
2
3
4

TIP

对于 username和userName这种情况希望大家多查查英文翻译软件，username为一个字典名词，不需要命名为 userName

# 请求参数

GET请求均以查询参数形式进行数据请求

GET http:127.0.0.1:8888/api/userInfo?id=123
1

除GET以外 文本请求均以application/json进行传输

WARNING

禁止查询参数混写，要么以查询参数形式要么以请求body。

不推荐 x-www-form-urlencoded形式传输数据。

# 字段类型

数据库存放字段类型应该和返回值字段类型保持一致

# 单复数












 



{
    code: 0,
    msg: "操作成功",
    data: {
        books: ["西游记", "三国演义"] //复数类型请遵守英文复数书写方式
    }
}
{
    code: 0,
    msg: "操作成功",
    data: {
        book: ["西游记", "三国演义"] //请严格遵守名词复数
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 禁止无关字段

# 请求参数

请求参数遵循够用即可

假设：需要查询当前用户基本信息(当前用户已登录，拥有token)，此时请求用户基本信息接口无需传递任何参数，只需要携带上token即可(不需要用户id)

# 返回结果

禁止返回与业务场景无关字段

TIP

无关字段会大大增加传输数据大小，同时增大调试困难。请开发人员务必遵循这一原则！！！

# 大数据分段

这是一个抽样单填写的例子 例子

返回值

TIP

返回值约 230个字段，对于开发人员来说面对这种非常庞大的表单填写信息，需要将数据进行分段处理。

//推荐数据格式
{
    A: {}, //抽样基本信息
    B: {}, //抽样单基本信息
    C: {}, //样品信息
    ...
}
1
2
3
4
5
6
7

# 空值规范

# 数字类型














 




 




 


//非空情况
{
    name: "shu",
    age: 18
}
//空值情况
{
    name: "shu",
    age: null //当年龄字段为非必填字段时
}
//不规范情况
{
    name: "shu",
                //缺少字段
}
//不规范情况
{
    name: "shu",
    age: "", //字段类型不一致
}
//不规范情况
{
    name: "shu",
    age: -1, //不推荐使用 -1 0这类值作为空值
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 字符串类型













 




 








//非空情况
{
    name: "shu",
    age: 18
}
//空值情况
{
    name: "", //姓名字段默认为空
    age: 18
}
///空值情况
{
    name: null, //姓名字段未填写
    age: 18
}
//不规范情况
{
           //不返回字段
    age: 18
}
//不规范情况
{
    name: " ", //强烈建议前后端针对字符串做trim处理，可以避免很多奇怪问题
    age: 18
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

TIP

字符串 "" 和 null 应该区分为完全不同的两种情况，前者代表该字段默认值为空，后者代表该字段未填写 在含义上区分这两种情况会增加代码可读性！！！

# 布尔值

















 





 


//非空情况
{
    name: "shu",
    age: 18,
    handsome: true
}
//空值情况
{
    name: "shu", 
    age: 18,
    handsome: null
}
//不规范情况
{
    name: "shu",
    age: 18,
           //不返回字段
}
//不规范情况
{
    name: "shu",
    age: 18,
    handsome: "true"  //格式不统一
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 日期格式

时间戳：非常方便计算的时间格式，同时时间戳可以避免一些时区导致的问题。

其他时间格式：直观的时间格式，适合展示不适合计算

TIP

  1. 时间戳是推荐时间格式，但是缺点是数据不直观，对于需要计算的时间推荐使用时间戳。
  2. 时间字段前端传递给后端数据格式 应该与 后端传递给前端的数据格式 保持一致。
  3. 根据前后端分离原则，后端不应该针对UI对日期数据进行格式化，应该交给前端来做。

WARNING

时间截至日期应该非常明确并且统一，假设用户在 2020/2/3 10:20 生成了一个订单，订单过期时间为2天，那么会存在两种算法计算该日期。

  1. 订单在 2020/2/5 10:20 过期
  2. 订单在 2020/2/5 00:00 过期

# 数组(List)














 




 


//非空情况
{
    name: "shu",
    books: ["西游记", "三国演义"],
}
//空值情况
{
    name: "shu", 
    books: [],
}
//不规范情况
{
    name: "shu",
           //不返回字段
}
//不规范情况
{
    name: "shu",
    books: null  //请后台小伙伴检查数据表是否设计合理
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 对象














 




 




//非空情况
{
    name: "shu",
    profile: {
        job: "typer"
    },
}
//空值情况
{
    name: "shu", 
    profile: {},
}
//不规范情况
{
    name: "shu",
           //不返回字段
}
//不规范情况???????????????
{
    name: "shu",
    books: null  
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 文档为准

返回数据格式应该与录入文档数据格式保持一致(字段名称，字段值类型，字段数量，字段结构，接受字段和返回字段相同)。

下面列举了常见格式不一致情况

//接口标准格式，调用接口 /api/userInfo
{
    code: 0,
    msg: "操作成功",
    data: {
        name: "shu",
        phone: 15228888888
    }
}
1
2
3
4
5
6
7
8
9





 




//字段名称不一致
{
    code: 0,
    msg: "操作成功",
    data: {
        username: "shu",
        phone: 15228888888
    }
}
1
2
3
4
5
6
7
8
9






 



//字段类型不一致
{
    code: 0,
    msg: "操作成功",
    data: {
        username: "shu",
        phone: "15228888888"
    }
}
1
2
3
4
5
6
7
8
9







 



//字段数量不一致
{
    code: 0,
    msg: "操作成功",
    data: {
        username: "shu",
        phone: 15228888888,
        age: 18
    }
}
1
2
3
4
5
6
7
8
9
10

# 常见数据格式

# 分页

---请求数据---

{
    pageNum: 2, //页码
    pageSize: 10, //每页数量
    ... //其他参数
}
1
2
3
4
5

---返回数据---

{
    code: 0,
    msg: "操作成功",
    data: {
        rows: [], //列表
        total: 10 //总数
    }
}
1
2
3
4
5
6
7
8

# 单选(多选)下拉

---返回数据---

{
    code: 0,
    msg: "操作成功",
    data: [
        {
            id: 1, //字段可根据实际替换
            name: "苹果" //字段可根据实际替换
        },
        {
            id: 2,
            name: "菠萝"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

TIP

id name可以根据实际字段替换，但字段个数通常不应该超过2个。

---多选请求参数格式---

  1. 若为GET请求
http://127.0.0.1:8080/foo?ids=1,2,3,4
1
  1. 若为非GET请求则统一放在请求body里面，以数组形式传递参数
//POST PUT DELETE
{
    ids: [1, 2, 3, 4],
}
1
2
3
4

← 简介 →