egg-reply

Restful API 接口响应结构定义 Egg 中间件，支持符合标准 HTTP 状态码 Restful API 标准和业界比较通用的 JSON 型 Restful API 标准。

文档目录

• egg-reply
  • 依赖说明
    • 依赖的 egg 版本
    • 依赖的插件
  • 开启插件
  • 使用场景
  • API
    • ctx.success
    • ctx.fail
    • ctx.exception
    • ctx.ok
    • ctx.created
    • ctx.noContent
    • ctx.badRequest
    • ctx.unauthorized
    • ctx.forbidden
    • ctx.notFound
    • ctx.conflict
    • ctx.serverError
    • ctx.reply
    • ctx.catch
  • 详细配置
  • 提问交流
  • License

依赖说明

依赖的 egg 版本

依赖的插件

无

开启插件

声明使用插件

// config/plugin.js
// CommonJS
exports.reply = {
  enable: true,
  package: 'egg-reply',
};
// ES6 Module
export default {
  reply: {
    enable: true,
    package: 'egg-reply',
  },
};

使用场景

方便定义前后端通信的数据结构，定义标准化的接口返回结构。能够在 Controller 或 Service 中 this.ctx.<method> 快捷定义返回信息结构。

import { Controller } from 'egg';
class OrderController extends Controller {
  public async index() {
    this.ctx.success([
      { id: 1, name: 'Ben' },
      { id: 2, name: 'Tom' },
      { id: 3, name: 'Jack' },
    ]);
    // Output:
    // {
    //   { id: 1, name: 'Ben' },
    //   { id: 2, name: 'Tom' },
    //   { id: 3, name: 'Jack' }
    // }
  }
}

API

ctx.success

表示接口处理成功，HTTP 状态码默认 200，code 字段默认 200, success 为 true。

语法：

this.ctx.success(data?: any, msg?: string, extra?: any)

ctx.fail

表示请求失败，HTTP 状态码默认 400，code 字段默认 400, success 为 false。

语法：

this.ctx.fail(code?: string, msg?: string)

ctx.exception

表示服务端请求处理失败，HTTP 状态码默认 500，code 字段默认 500, success 为 false。

语法：

this.ctx.exception(code?: string, msg?: string)

ctx.ok

HTTP 状态码为 200，通常用于 HTTP GET 请求的结果，表示成功，。

this.ctx.ok(data?: any, extra?: any)

ctx.created

HTTP 状态码为 201，通常用于 HTTP POST 请求的结果，表示已在服务器上成功创建了一个或多个新资源。

this.ctx.created(data?: any, extra?: any)

ctx.noContent

HTTP 状态码为 204，表示服务器已成功完成请求，并且在响应有效负载正文中没有要发送的内容。服务器可能希望以 entity-headers 的形式返回更新的元信息，如果存在，应该将其应用于当前文档的活动视图（如果有的话）。

this.ctx.noContent();

ctx.badRequest

HTTP 状态码为 400，表示请求参数错误。

this.ctx.badRequest(data?: any, msg?: string, extra?: any);

ctx.unauthorized

HTTP 状态码为 401，表示请求需要身份验证。

this.ctx.unauthorized(data?: any, msg?: string, extra?: any);

ctx.forbidden

HTTP 状态码为 403，表示没有权限访问该请求，服务器收到请求但拒绝提供服务。

this.ctx.forbidden(data?: any, msg?: string, extra?: any);

ctx.notFound

HTTP 状态码为 404，表示用户请求的资源不存在。

this.ctx.notFound(data?: any, msg?: string, extra?: any);

ctx.conflict

HTTP 状态码为 409，表示因为请求存在冲突无法处理。例如通过手机号码提供注册功能得 API，当用户提交的手机号已存在时，必须返回此状态码。

this.ctx.conflict(data?: any, msg?: string, extra?: any);

ctx.serverError

HTTP 状态码为 500，在服务器出错时跑出，对于所有的 500 错误，都应该提供完整的错误信息支持，方便追踪调试。

this.ctx.serverError(data?: any, msg?: string, extra?: any);

ctx.reply

自定义响应数据内容

this.ctx.reply({ status, code, data, success, msg, extra });

ctx.catch

捕捉错误时使用，HTTP 状态码为 500

try {
  throw new Error('Hello world!');
} catch (err) {
  this.ctx.catch(err);
}

详细配置

请到 config/config.default.js 查看详细配置项说明。

提问交流

请到 egg issues 异步交流。

License

MIT