Dot520 文档中心

主题

Dot5202025-04-14
594
2.2m

开放接口 ​

Swagger ​

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

什么是 RESTful 风格 ​

REST（Representational State Transfer）是一种互联网应用程序的 API 设计理念。其核心思想是通过 URL 定位资源，并使用 HTTP 动词（GET、POST、DELETE、PUT、HEAD）来描述对资源的操作。

RESTful 架构的特点：

  • 资源：每个资源都有一个唯一的 URL 地址。
  • 操作：使用 HTTP 动词来操作资源。
  • 表示：通过数据格式（如 JSON 或 XML）表示资源的状态。

简单来说：

  • URL 地址中只包含名词表示资源。
  • 使用 HTTP 动词表示对资源的操作。

参考资料 ​

统一规范化接口处理 ​

RESTful API ​

RESTful API 是一种基于 HTTP 协议的网络应用程序架构风格。通过定义资源（资源的 URL）、操作（HTTP 方法）和表示（数据格式），RESTful API 提供了一种简单而有效的方法来处理接口请求。

优点：

  • 统一接口：易于理解和使用。
  • 无状态：每个请求都包含所有必要的信息。
  • 可扩展性：支持多种数据格式（如 JSON、XML）。

Malus 中的统一返回格式 ​

在 Malus 中，HTTP 状态码仅使用 401 和 200 两种。具体返回格式如下：

响应状态码 ​

  • 200：正常返回，无错误。
  • 207：业务错误提示。
  • 401：无授权（未登录、Token 过期、未授权）。
  • 400：业务异常（数据验证不通过等）。
  • 500：服务器内部错误。

响应格式 ​

json
// 正常返回
{
  "code": 200,
  "message": "成功",
  "body": "3a082eb833d0497aa6ff31eb3a9f31fd"
}

// 业务错误提示
{
  "code": 207,
  "message": "演示环境,禁止操作",
  "body": null
}

// 无授权
{
  "code": 401,
  "message": "提供的令牌无效或已过期，请重新登录",
  "body": ""
}

// 业务异常返回
{
  "code": 400,
  "message": "数据验证不通过！",
  "body": [
    "The Account field is required."
  ]
}

总结 ​

  • Swagger：用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
  • RESTful API：基于 HTTP 协议的架构风格，提供统一接口。
  • Malus 中的统一返回格式：使用固定的 HTTP 状态码和统一的 JSON 格式返回响应，便于客户端处理。

更多关于 Swagger 和 RESTful API 的知识，可参考 Swagger 官方文档 和 RESTful API 设计指南。

最近更新