接口文档设计：从不同角度进行功能分析

前言

开发过程的前后端分离是基于在约定好的接口文档的基础之上的，也就是说：接口文档是服务端开发和前端开发的指导性文件，而完成前面的需求分析和数据库设计就是为了合理高效地设计好接口文档。

完成了需求分析和数据库设计，就可以参照功能树和数据结构来设计接口文档了。本篇带领大家对 Keller 云笔记项目的接口文档做初步的设计。

设计原则

在需求分析和数据库设计完成的基础上设计出的接口文档也并不能达到完美，而是能尽可能地符合最优的业务流程和数据结构，有其他不足或不合理的地方在开发过程中经过双方沟通后修改就可以了。在接口文档设计的过程中要符合 4 个原则：格式统一、权限明确、单一性、扩展性

格式统一

格式统一包含请求格式统一和应答格式统一，统一的格式可以减少前端和服务端在开发过程中出错的几率，降低沟通成本。

权限明确

不同权限的接口分开设计，比如：不需要登录就能访问的接口、需要登录才能访问的接口、只有管理员可以访问的接口，区分设计的好处是在于方便接口权限的统一管理。

单一性

单一性原则是指，一个接口就只做单一的一件事情，不要在一个接口中返回多个业务的数据。接口粒度要合适，比如：登录接口就负责用户登录，不应该返回用户名片、用户笔记本列表等其他数据。

扩展性

接口的扩展性往往与接口的粒度有关，小一点的粒度更适合扩展，调用更加灵活。不要在一个接口中处理过多的工作，应把主动权交给前端。

格式说明

请求格式

本文档中除了上传头像接口 2003 外，都是 JSON 格式的，在调用需要身份验证的接口时，需要在 Header 中添加 token 字段，值为登录时获取到的 JWT，如：

POST /api
Content-Type:application/json
method:"userCard"
token:token
Body:{
    "nickName":"往后余生"
}

应答格式

本文档中所有接口的应答格式都是一致的，应答报文的 Body 都是 JSON 格式，主要分为成功应答和失败应答两种。

成功应答

业务处理成功，HTTP Status 为 200 OK，Body 内容如下：

{
    "success": 0,
    "data": Object
}

参数说明：

• success：业务状态，成功应答的业务状态固定为 0
• data：业务数据，数据类型由具体接口指定

失败应答

失败应答分为两种：HTTP 处理失败和业务失败，如果 HTTP Status 为 200 OK，则说明是业务失败；否则说明是 HTTP 处理失败。Body 内容格式如下：

{
    "success": 1,
    "message": "失败信息描述"
}

参数说明：

• success ：业务状态，失败应答的业务状态固定为 1
• message：失败信息描述，由具体接口指定

基础接口（不需要身份验证）

1001 获取注册邮件验证码

该接口用于用户在注册前获取邮件验证码。

请求示例：

GET /base/getCodeForRegister?email=2221167890@qq.com

参数说明：

• email：要注册的邮箱账号

成功应答：

• success：0
• data：null

失败应答：

• success：1
• message：账号已被注册、邮件发送失败等

1002 根据邮件验证码注册账号

该接口用于收到注册验证邮件后，填写验证码并设置密码以注册用户。如果注册成功，返回注册好的用户 ID；否则，返回错误。

请求示例：

POST /base/register
Content-Type:application/json
Body:
    {
        "email":"2221167890@qq.com",
        "code":"gr3HDH",
        "password":"123456"
    }

参数说明：

• email：邮箱账号
• code：验证码
• password：密码

成功应答：

• success：0
• data：数值类型，注册生成的用户ID

失败应答：

• success：1
• message：验证码错误或已过期，请重新获取

1003 账号密码登录

该接口用于使用账号密码登录。

请求示例：

POST /base/login
Content-Type:application/json
Body:
    {
        "email":"2221167890@qq.com",
        "password":"123456"
    }

请求参数说明：

• email：邮箱账号
• password：登录密码

成功应答：

• success：0
• data：字符类型，用户 Token

失败应答：

• success：1
• message：账号密码错误或账号不存在

1004 获取登录邮件验证码

该接口用户获取登录的邮件验证码。

请求示例：

GET /base/getCodeForLogin?email=2221167890@qq.com

请求参数：

• email：要登录的邮箱地址

成功应答：

• success：0
• data：null

失败应答：

• success：1
• message：账号不存在

1005 验证码登录

该接口用于验证码登录。

请求示例：

POST /base/loginWithCode
Content-Type:application/json
Body:
    {
        "email":"2221167890@qq.com",
        "code":"lnwSa21",
        "type":0
    }

请求参数说明：

• email：邮箱账号
• code：邮件验证码
• type：用户类型：0 普通用户；100 管理员

成功应答：

• success：0
• data：字符类型，用户 Token

失败应答：

• success：1
• message：邮件验证码已过期或不正确，请重新获取

1006 发送重置密码邮件

该接口用于用户忘记密码时发送重置密码邮件：

POST /base/sendResetPasswordEmail?email=email

请求参数说明：

• email：邮箱账号

成功应答：

• success：0

失败应答：

• success：1
• message：账号尚未注册

1007 根据邮件重置密码

POST /base/resetPasswordByEmail?password=654321&token=token

请求参数说明：

• password：新密码
• token：用户身份验证令牌

成功应答：

• success：0

失败应答：

• success：1
• message：密码重置失败

用户信息（需要身份验证）

2001 设置名片

该接口用于设置用户个人名片。

请求示例：

POST /api
Content-Type:application/json
method:"userCard"
token:token
Body:{
    "nickName":"往后余生",
    "email":"2221167890@qq.com",
    "label":"Stay Hungry Stay Foolish"
}

请求参数说明：

• nickName：用户昵称
• email：要在名片上展示的邮箱地址，和注册邮箱地址无关
• label：个性签名

成功应答：

• success：0
• data：null

失败应答：

• success：1
• message：账号不存在

2002 查看个人名片

GET /api
Content-Type:application/json
method:"userCard"
token:token

成功应答：

• success
• data：
• nickName
• email
• label
• imgUrl
• thumUrl

失败应答：

• success：1
• message：账号不存在

2003 上传头像

POST /upload
token:token
Body:file

成功应答：

• success

失败应答：

• success：1
• message：账号不存在

2004 修改密码

POST /api
Content-Type:application/json
method:"userInfo/setPassword"
token:token
Body:{
    "password":"123456",
}

请求参数说明：

• password：新密码
• token：用户身份验证令牌

成功应答：

• success：0

失败应答：

• success：1
• message：密码重置失败

笔记本（需要身份验证）

3001 新建笔记本

POST /api
Content-Type:application/json
method:"notes"
token:token
Body:{
    "title":"标题",
    "subTitle":"副标题",
    "sort":1
}

请求参数说明：

• title：笔记本标题
• subTitle：笔记本副标题
• sort：笔记本排序

成功应答：

• success：0

失败应答：

• success：1
• message：用户未登录

3002 修改笔记本

POST /api
Content-Type:application/json
method:"notes/update"
token:token
Body:{
    "id":1,
    "title":"标题",
    "subTitle":"副标题",
    "sort":1
}

请求参数说明：

• id：笔记本 ID
• title：笔记本标题
• subTitle：笔记本副标题
• sort：排序

成功应答：

• success：0

失败应答：

• success：1
• message：修改失败

3003 删除笔记本

POST /api
Content-Type:application/json
method:"notes/delete"
token:token
Body:{
    "id":1
}

请求参数说明：

• id：笔记本 ID

成功应答：

• success：0

失败应答：

• success：1
• message：用户未登录

3004 获取笔记本列表

GET /api
Content-Type:application/json
method:"notes"
token:token

成功应答：

• success：0
• data：笔记本列表，JSON 数组，数组内每一项格式如下：
• id：笔记本 ID
• title：笔记本标题
• subTitle：笔记本副标题
• createTime：笔记本创建时间
• sort：笔记本排序

失败应答：

• success：1
• message：用户未登录

笔记

4001 新建笔记

POST /api
Content-Type:application/json
method:"note"
token:token
Body:{
    "notesId":1,
    "title":"标题",
    "content":"内容",
    "sort":1
}

请求参数说明：

• notesId：笔记本 ID
• title：笔记标题
• content：笔记内容
• sort：笔记排序

成功应答：

• success：0

失败应答：

• success：1
• message：创建笔记失败

4002 编辑笔记

POST /api
Content-Type:application/json
method:"note/update"
token:token
Body:{
    "id":1,
    "notesId":1,
    "title":"标题",
    "content":"内容",
    "sort":1
}

请求参数说明：

• id：笔记 ID
• notesId：笔记本 ID
• title：笔记标题
• content：笔记内容
• sort：笔记排序

成功应答：

• success：0

失败应答：

• success：1
• message：笔记不存在

4003 获取笔记列表

GET /api
Content-Type:application/json
method:"note/getList"
token:token
Body:{
    "notesId":1
}

请求参数说明：

• title：笔记本 ID

成功应答：

• success：0
• data：笔记列表，json 数组，数组内每一项格式如下：
• id：笔记 ID
• notesId：笔记本 ID
• title：笔记标题
• sort：排序
• createTime：创建时间
• updateTime：最后一次修改时间

失败应答：

• success：1
• message：用户未登录

4004 获取笔记内容

GET /api
Content-Type:application/json
method:"note"
token:token
Body:{
    "id":1
}

请求参数说明：

• id：笔记 ID

成功应答：

• success：0
• data：笔记详情，json 格式，字段组成如下：
• id：笔记 ID
• notesId：笔记本 ID
• title：笔记标题
• sort：排序
• content：笔记内容
• createTime：创建时间
• updateTime：最后一次修改时间

失败应答：

• success：1
• message：用户未登录

管理员功能

5001 查询用户信息

GET /api
Content-Type:application/json
method:"admin/userInfo"
token:token
Body:{
    "id":1
}

请求参数说明：

• id：用户 ID

成功应答：

• success：0
• data：用户信息，字段如下：
• id：用户 ID
• type：用户类型
• email：注册邮箱
• createTime：注册时间
• status：账号状态

失败应答：

• success：1
• message：该用户不存在

5002 查询用户列表

GET /api
Content-Type:application/json
method:"admin/userInfoList"
token:token

成功应答：

• success：0
• data：用户信息数组，数组中每一项字段如下：
• id：用户 ID
• type：用户类型
• email：注册邮箱
• createTime：注册时间
• status：账号状态

失败应答：

• success：1
• message：没有权限

5003 查询用户日活跃量

GET /api
Content-Type:application/json
method:"admin/activeByDay"
token:token
Body:{
    "date":"20200320",
    "days":10
}

请求参数说明：

• date：要查询的日期，格式为：yyyyMMdd
• days：要查询的天数

成功应答：

• success：0
• data：指定查询日期 date 前 days 天（含 date 当天）的用户日活跃量数组，字段如下：
• count：日活跃量

失败应答：

• success：1
• message：权限限制

5004 查询用户月活跃量

GET /api
Content-Type:application/json
method:"admin/activeByMonth"
token:token
Body:{
    "date":"202003",
    "months":3
}

请求参数说明：

• date：要查询的日期，格式为：yyyyMM
• months：要查询的月数

成功应答：

• success：0
• data：指定查询日期 date 前 month 月（含 date 当月）的用户月活跃量数组，字段如下：
• count：月活跃量

失败应答：

• success：1
• message：权限限制

5005 查询用户日增长量

GET /api
Content-Type:application/json
method:"admin/incrByDay"
token:token
Body:{
    "date":"20200320",
    "days":10
}

请求参数说明：

• date：要查询的日期，格式为：yyyyMMdd
• days：要查询的天数

成功应答：

• success：0
• data：指定查询日期 date 前 days 天（含 date 当天）的用户日增长量数组，字段如下：
• count：日增长量

失败应答：

• success：1
• message：权限限制

5006 查询用户月增长量

GET /api
Content-Type:application/json
method:"admin/incrByMonth"
token:token
Body:{
    "date":"202003",
    "months":10
}

请求参数说明：

• date：要查询的日期，格式为 yyyyMM
• months：要查询的月数

成功应答：

• success：0
• data：指定查询日期 date 前 months 月（含 date 当月）的用户月活跃量数组，字段如下：
• count：月活跃量

失败应答：

• success：1
• message：权限限制

5007 查询总用户量

GET /api
Content-Type:application/json
method:"admin/userCount"
token:token

成功应答：

• success：0
• data：用户总数

失败应答：

• success：1
• message：权限限制

小结

本篇带领大家依据 Keller 云笔记的功能树和数据结构，定义好接口文档，保证项目开发过程条理清晰、功能明确。有了接口文档，前端和后端就能在一起愉快地玩耍了~

答疑与交流

为了方便与作者交流与学习，GitChat 编辑团队组织了一个专栏读者交流群，添加小助手-伽利略微信：「Linmicc」，回复关键字「950」给小助手伽利略获取入群资格。