前后端接口约定

在线接口文档

大纲链接 §

[toc]

后端接口规范 ⇧

约定接口一般包括以下数据

  • 0.后端接口线上地址根路径： https://blog-server.hunger-valley.com
  • 1.功能简介
  • 2.当前接口的路径： 如 /auth/register
  • 3.当前接口提交数据HTTP方法类型是什么? 如
    • GET 获取数据
    • POST 提交或者创建
    • PATCH 修改数据，部分修改，只需要传递需要修改的参数，语义为补丁
    • DELETE 删除数据
    • PUT 修改数据，整体替换原有数据，需包含全部参数（本项目暂不使用）
  • 4.参数类型/格式，比如是 application/json 格式，还是 application/x-www-form-urlencoded的数据格式
  • 5.参数字段，及限制条件
  • 6.是否需要登录权限（身份认证）
  • 7.返回成功的数据格式
  • 8.返回失败的数据格式

按照本项目业务逻辑分类的接口

  • 认证相关
  • 博客相关

开发阶段可以使用 postman 等工具 或者 curl 命令测试接口

  • 按照文档，mock 数据
  • 替换上线地址

认证相关 ⇧

分为以下几个接口

类型 路径 功能
POST /auth/register 用户注册
POST /auth/login 用户登录
GET /auth 判断用户是否登录
GET /auth/logout 注销登录

POST 路径 /auth/register ⇧

  • 功能: 用户注册
  • 提交参数
    • 参数类型: Content-Type: application/x-www-form-urlencoded;charset=utf-8
    • 参数字段
      • username : 用户名,长度1到15个字符，只能是字母数字下划线中文
      • password : 密码, 长度6到16个任意字符
  • 是否需要登录权限（身份认证）：否
  • 返回数据
    • 失败返回格式: {"status": "fail", "msg": "错误原因"}
    • 成功返回格式:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "status": "ok",
  "msg": "注册成功",
  "data": {
    "id": 1,
    "username": "hunger",
    "avatar": "http://avatar.com/1.png",
    "updatedAt": "2021-12-27T07:40:09.697Z",
    "createdAt": "2021-12-27T07:40:09.697Z"
  }
}

使用curl测试接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# -d 是用来传递数据
# 对于声明请求类型比如 POST 和 PUT 可以这样使用：
# -X POST
# -X PUT
# 对于 GET，不用加 -X 来声明请求类型
curl -d "username=hunger&password=123456" -X POST "https://blog-server.hunger-valley.com/auth/register"

# 示例
curl -d "username=hunger1&password=123456" -X POST "https://blog-server.hunger-valley.com/auth/register"
curl -d "username=hunger3&password=123456" -X POST "https://blog-server.hunger-valley.com/auth/register"
  • 数据格式为application/x-www-form-urlencoded，即可使用username=hunger&password=123456的形式传递数据

POST 路径 /auth/login ⇧

  • 功能: 用户登录
  • 提交参数
    • 参数类型: Content-Type: application/json;charset=utf-8
    • 参数字段
      • username : 用户名, 长度1到15个字符，只能是字母数字下划线中文
      • password : 密码, 长度6到16个任意字符
  • 是否需要登录权限（身份认证）：否
  • 返回数据
    • 失败返回格式： {"status": "fail", "msg": "用户不存在"} 或者 {"status": "fail", "msg": "密码不正确"}
    • 成功返回格式：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "status"："ok",
  "msg": "登录成功",
  "data": {
    "id": 1,
    "username": "hunger",
    "avatar: "头像 url",
    "createdAt": "2021-12-27T07:40:09.697Z",
    "updatedAt": "2021-12-27T07:40:09.697Z"
  }
}

使用curl测试接口

1
2

# -i 查看服务器返回的详细响应头和响应体
curl -d "username=hunger1&password=123456" "https://blog-server.hunger-valley.com/auth/login" -i
  • 其中-d表示请求参数或者发送POST请求时设置请求体
    • -d '内容'或者--data '内容'
  • -i 查看服务器返回的详细 响应头 和 响应体
  • 如果后端使用Session-Cookie机制来实现登录认证
    • 则响应头中有set-cookie字段，将其值connect.sid=xxx...xxx记录下来
    • 之后如果发送需要权限的接口时，携带上这个字段，就可处于登录状态，例如：
      • 测试是否登陆curl "https://blog-server.hunger-valley.com/auth -b "connect.sid=xxx...xxx"
      • 测试是否注销curl "https://blog-server.hunger-valley.com/auth/logout -b "connect.sid=xxx...xxx"
  • 如果后端使用JWT机制来实现登录认证
    • 则响应头中有"token"字段，例如"token":"Bearer xxxx.xxxxx.xxxx"
    • 之后如果发送需要权限的接口时，携带上"authorization"字段，值为"Bearer xxxx.xxxxx.xxxx"，就可以登录状态，访问需要权限的接口
  • 本项目改为使用JWT机制实现身份认证

GET 路径 /auth ⇧

  • 功能: 判断用户是否登录
  • 提交参数: 无
  • 是否需要登录权限（身份认证）：是/否
  • 返回数据
  1. 已登录的情况：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "status": "ok"
  "isLogin": true,
  "data": {
    "id": 1,
    "avatar": "http://avatar.com/1.png",
    "username": "hunger",
    "updatedAt": "2021-12-27T07:40:09.697Z",
    "createdAt": "2021-12-27T07:40:09.697Z"
  }
}
  1. 未登录的情况：
1
2
3
4

{
  "status": "ok"
  "isLogin": false
}

使用curl测试接口，范例：

1

curl "https://blog-server.hunger-valley.com/auth" -H "authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkphY2t5IiwiaWQiOjUyNywiaWF0IjoxNjQzNjcyODgzLCJleHAiOjE2NDM 5MzIwODN9.1rnU6E-yo-nK_GBb8dfuDzx_Kq-qjAKaZYzFjo5uQ_0"
  • curl "https://blog-server.hunger-valley.com/auth" -H "..."中的 -H 表示 设置请求头
  • 例如-H 'Name:Value'或者--header 'Name:Value'，单引号内必须是以键值对的形式

GET 路径 /auth/logout ⇧

  • 功能: 注销登录
  • 提交参数: 无
  • 是否需要登录权限（身份认证）：是
  • 返回数据:
    • 失败返回格式： {"status": "fail", "msg": "用户尚未登录"}
    • 成功返回格式： {"status": "ok", "msg": "注销成功"}

博客相关 ⇧

分为以下几个接口

类型 路径 功能
GET /blog 获取博客列表
GET /blog/:blogId 获取博客详情
POST /blog 创建博客
PATCH /blog/:blogId 修改博客
DELETE /blog/:blogId 删除博客

GET 路径 /blog ⇧

  • 功能: 获取博客 列表
  • 提交参数:
    • page: 页码
      • 不传默认 page 值为1
      • 分页页码小于总页码
      • 如果设置该参数，则获取博客列表的第 page 页博客列表
    • userId: 用户 id
      • 不传则默认获取全部用户的数据
      • 如果设置，则获取该id用户的博客列表
    • atIndex: 是否展示在首页
      • 传递 true 则只得到显示到首页的博客列表
      • 不传，则默认得到全部类型(包括展示到首页和不展示到首页)的博客列表
      • false 得到不展示到首页的列表，如 /blog?page=2&userId=1 获取属于用户1的第2页博客列表
  • 是否需要登录权限（身份认证）：否
  • 返回数据:
    • 失败返回格式：{"status": "fail", "msg": "系统异常，无法获取博客信息"}
    • 成功返回格式：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "status": "ok",
  "msg": "获取成功",
  "total": 200, // 全部博客的总数
  "page": 2, // 当前页数
  "totalPage": 10, // 总页数
  "data": [
    {
      "id": 1, // 博客 id
      "title": "博客标题",
      "description": "博客内容简要描述",
      "user": {
        "id": 100, // 博客所属用户 id,
        "username": "张三", // 博客所属用户的 username
        "avatar": "头像url"
      },
      "createdAt": "2021-12-27T08:22:56.792Z", // 创建时间
      "updatedAt": "2021-12-27T08:22:56.792Z" // 更新时间
    },
    ... // 其他
  ]
}
  • 数据中不需要博客正文

GET 路径 /blog/:blogId ⇧

  • 功能: 获取 id 为 blogId 的博客 详情， 如 /blog/1
  • 提交参数: 无
  • 是否需要登录权限（身份认证）：否
  • 返回数据:
    • 失败返回格式：{"status": "fail", "msg": "系统异常，无法获取博客信息"}
    • 成功返回格式：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "status": "ok",
  "msg": "获取成功",
  "data": {
      "id": 1, //博客 id
      "title": "博客标题",
      "description": "博客内容简要描述",
      "content": "博客正文内容，字比较多...",
      "user": {
        "id": 100, // 博客所属用户 id,
        "username": "张三", // 博客所属用户 username
        "avatar": "头像url"
      },
      "createdAt": "2021-12-27T08:22:56.792Z", // 创建时间
      "updatedAt": "2021-12-27T08:22:56.792Z" // 更新时间
    }
}

POST 路径 /blog ⇧

  • 功能: 创建博客
  • 提交参数
    • 参数类型: Content-Type: application/json; charset=utf-8
    • 参数字段
      • title : 博客标题, 博客标题不能为空，且不超过100个字符
      • content : 博客内容, 博客内容不能为空，且不超过10000个字符
      • description: 博客内容简要描述，可为空，如果为空则后台自动从 content 中提取
  • 是否需要登录权限（身份认证）：是
  • 返回数据：
    • 失败返回格式： {"status": "fail", "msg": "登录后才能操作"}
    • 成功返回格式：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "status": "ok",
  "msg": "创建成功",
  "data": {
      "id": 1, // 博客 id
      "title": "博客标题",
      "description":  "博客内容简要描述",
      "content": "博客正文内容...",
      "user": {
        "id": 100, // 博客所属用户 id,
        "username": "张三", // 博客所属用户 username
        "avatar": "头像url"
      },
      "createdAt": "2021-12-27T08:22:56.792Z",   // 创建时间
      "updatedAt": "2021-12-27T08:22:56.792Z"   // 更新时间
    }
}

命令行测试范例：

1

curl -d "title=hello&content=world&description=jiojio..." -X POST "https://blog-server.hunger-valley.com/blog" -H "authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkphY2t5IiwiaWQiOjUyNywiaWF0IjoxNjQzNjcyODgzLCJleHAiOjE2NDM 5MzIwODN9.1rnU6E-yo-nK_GBb8dfuDzx_Kq-qjAKaZYzFjo5uQ_0"

PATCH 路径 /blog/:blogId ⇧

  • 功能: 修改 博客 id 为:blogId 的博客
  • 范例: /blog/1
  • 提交参数
    • 参数类型: Content-Type: application/json; charset=utf-8
    • 参数字段:
      • title: 博客标题, 可选，不传则维持之前的内容
      • content: 博客内容, 可选，不传则维持之前的内容
      • description: 博客内容简要描述, 可选，不传且正文不变则维持之前的内容
      • atIndex: true | false， 是否展示到首页, 可选
  • 是否需要登录权限（身份认证）：是
  • 返回数据:
    • 失败返回格式：
      • {"status": "fail", "msg": "登录后才能操作"}
      • {"status": "fail", "msg": "博客不存在"}
      • {"status": "fail", "msg": "无法修改别人的博客"}
    • 成功返回格式：
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "status": "ok",
  "msg": "修改成功",
  "data": {
      "id": 1, // 博客 id
      "title": "博客标题",
      "description":  "博客内容简要描述",
      "content": "博客内容",
      "user": {
        "id": 100, // 博客所属用户 id,
        "username": "", // 博客所属用户 username
        "avatar": "头像url"
      },
      "createdAt": "2021-12-27T08:22:56.792Z", // 创建时间
      "updatedAt": "2021-12-27T08:22:56.792Z" // 更新时间
    }
}

命令行测试范例：

1

curl -d "title=hello100&content=world100&description=jiojio1000" -X PATCH "https://blog-server.hunger-valley.com/blog" -H "authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkphY2t5IiwiaWQiOjUyNywiaWF0IjoxNjQzNjcyODgzLCJleHAiOjE2NDM 5MzIwODN9.1rnU6E-yo-nK_GBb8dfuDzx_Kq-qjAKaZYzFjo5uQ_0"

DELETE 路径 /blog/:blogId

  • 功能: 删除 博客 id 为:blogId 的博客
  • 提交参数：无
  • 是否需要登录权限（身份认证）：是
  • 返回数据
    • 失败返回格式：
      • {"status": "fail", "msg": "登录后才能操作"}
      • {"status": "fail", "msg": "博客不存在"}
      • {"status": "fail", "msg": "无法删除别人的博客"}
    • 成功返回格式：{"status": "ok", "msg": "删除成功"}

命令行测试范例：

1

curl -X DELETE "https://blog-server.hunger-valley.com/blog/12" -H "authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkphY2t5IiwiaWQiOjUyNywiaWF0IjoxNjQzNjcyODgzLCJleHAiOjE2NDM 5MzIwODN9.1rnU6E-yo-nK_GBb8dfuDzx_Kq-qjAKaZYzFjo5uQ_0"