数据结构

Dux Refine 默认定义了 API 数据结构，您需要根据文档中的说明返回相应的接口格式和字段，Dux Next 后端数据结构默认为该结构。

数据格式

API 返回的数据需要采用 json 数据格式，接口 URL 应遵循基本的 RESTful API 格式，不管是不是 200 状态码，返回的 json 数据格式都应包含以下字段：

{
  "code": 200,
  "message": "ok",
  "data": {
    ...
  },
  "meta": {
    ...
  }
}

请求头

前端发出请求时，会携带以下通用的请求头信息：

• Accept-Language 请求语言，API 可以使用该参数返回对应语言的数据或信息。
• Authorization 用户认证，登录后每次请求都会带上该参数，API 需要自行验证其有效性 (Dux Next 已自带验证)。

Accept-Language: zh-CN
Authorization: Bearer <token>

成功消息

API 返回成功消息。

{
  "code": 200,
  "message": "ok",
  "data": {}
}

错误消息

API 返回错误消息，并且 http 状态码也为对应的 code。

{
  "code": 500,
  "message": "Error description",
  "data": {}
}

登录请求

登录时，会将以下 json 参数作为请求体内容。

{
  "username": "admin",
  "password": ""
}

登录成功后，需要返回至少以下字段信息。此外，还可以存储其他额外字段信息，供自定义使用。

{
  "code": 200,
  "message": "ok",
  "data": {
    "userInfo": {
      "username": "admin",
      "nickname": "Dux",
      "avatar": "http://xxx"
    },
    "token": "Bearer <token>",
    "permission": {}
  }
}

登录检查

登录后会不定时的请求登录检查接口验证登录状态和更新用户信息，该接口需要返回与登录成功后内容格式一致的数据。

登录失效

登录失效或 Token 验证失败时，需要返回状态码为 401。

{
  "code": 401,
  "message": "Login failure",
  "data": {}
}

自动续期

当检测到 token 即将过期时，请在 headers 头中返回 Authorization: Bearer <token> token 为续期后的授权内容，框架会自动进行覆盖 token。

用户权限

登录时，后端需要返回 permission 字段作为用户权限。如果该字段为空，则不限制权限。该权限仅用于前端验证，并且权限与资源对应，API 端需要自行判断接口权限。权限结构如下：

{
  "permission": {
    "user.list": true,      // 列表
    "user.create": false,   // 创建
    "user.edit": false,     // 编辑
    "user.delete": false,   // 删除
    "user.show": false,     // 详情
    ...
  }
}

权限的 key 使用了 资源名.动作 的命名方式，value 表示是否拥有该权限。

列表数据

列表数据使用 GET 请求，基本 URL 如下：

GET http://example.test/article

数据返回分为分页和非分页数据，API 需要返回以下基本格式：

• list 数组数据
• total 数据总数，对于非分页数据，此字段无效

{
  "code": 200,
  "message": "ok",
  "data": [
    ...
  ],
  "meta": {
    "total": 100
  }
}

对于分页请求，需要使用 page 参数表示页码，如下：

http://example.test/article?page=1

单条数据

单条数据使用 GET 请求，基本 URL 如下：

GET http://example.test/article/{id}

API 需要返回以下数据：

• info 详情数据

{
  "code": 200,
  "message": "ok",
  "data": {
    ...
  },
  "meta": {
    ...
  }
}

创建数据

创建数据使用 POST 请求，基本请求 URL 和数据如下，成功后返回成功消息。

POST http://example.test/article

BODY 
{
  "title": "...",
  ...
}

编辑数据

编辑数据使用 PUT 请求，基本请求 URL 和数据如下，成功后返回成功消息。

PUT http://example.test/article/{id}

BODY 
{
  "title": "...",
  ...
}

修改数据

修改单个字段数据使用 PATH 请求，基本请求 URL 和数据如下，成功后返回成功消息。

PATH http://example.test/article/{id}

BODY 
{
  "title": "..."
}

删除数据

删除数据使用 DELETE 请求，基本请求 URL 如下，成功后返回成功消息。

DELETE http://example.test/article/{id}