mm_ret

A Node.js module for generating JSON-RPC 2.0 compliant responses and requests. 提供便捷的方法来生成标准的JSON-RPC 2.0响应和请求。

安装 / Installation

npm install mm_ret

快速开始 / Quick Start

基本使用 / Basic Usage

const { Ret, Req, Error } = require('mm_ret');

// 生成成功响应 / Generate success response
const successResponse = Ret.body('操作成功');
console.log(successResponse);
// 输出: {"result":"操作成功"}

// 生成错误响应 / Generate error response
const errorResponse = Ret.error(10000, '参数错误');
console.log(errorResponse);
// 输出: {"error":{"code":10000,"message":"参数错误"}}

// 生成请求 / Generate request
const req = new Req('user');
const requestBody = req.send('getUser', { id: 123 });
console.log(requestBody);
// 输出: {"jsonrpc":"2.0","method":"user.getUser","params":{"id":123},"id":"..."}

功能特性 / Features

• ✅ JSON-RPC 2.0 标准兼容 - 完全符合JSON-RPC 2.0规范
• ✅ 多种响应类型 - 支持对象、列表、布尔值等响应格式
• ✅ 错误码管理 - 内置标准错误码和自定义错误码
• ✅ 请求模板 - 支持请求参数模板功能
• ✅ 轻量级 - 无依赖，体积小巧
• ✅ TypeScript 支持 - 提供完整的类型定义

API 文档 / API Documentation

Ret 类 - 响应生成器

生成符合JSON-RPC 2.0标准的响应对象。

方法 / Methods

body(result, error, id)

生成基础的JSON-RPC响应体。

参数:

• result {any} - 返回结果
• error {Object} - 错误信息（可选）
• id {String} - 请求ID（可选）

返回值: {Object} JSON-RPC响应对象

error(code, message, id)

生成错误响应。

参数:

• code {Number} - 错误码
• message {String} - 错误信息
• id {String} - 请求ID（可选）

返回值: {Object} 包含错误信息的响应对象

list(list, count, id)

生成列表类型的响应。

参数:

• list {Array} - 数据列表
• count {Number} - 总数量（可选）
• id {String} - 请求ID（可选）

返回值: {Object} 包含列表数据的响应对象

obj(obj, id)

生成对象类型的响应。

参数:

• obj {Object} - 返回的对象
• id {String} - 请求ID（可选）

返回值: {Object} 包含对象数据的响应对象

bl(bl, tip, id)

生成布尔类型的响应。

参数:

• bl {Boolean} - 布尔值
• tip {String} - 提示信息（可选）
• id {String} - 请求ID（可选）

返回值: {Object} 包含布尔值和提示信息的响应对象

Req 类 - 请求生成器

生成符合JSON-RPC 2.0标准的请求对象。

构造函数

new Req(scope = 'sys')

参数:

• scope {String} - 作用域，默认为"sys"

方法 / Methods

send(method, params)

生成JSON-RPC请求。

参数:

• method {String} - 方法名
• params {Object} - 参数对象

返回值: {Object} 标准的JSON-RPC请求对象

Error 类 - 错误码管理

管理JSON-RPC标准错误码和自定义错误码。

方法 / Methods

get(keyword)

根据关键词或错误码获取对应的错误信息。

参数:

• keyword {String|Number} - 关键词或错误码

返回值: {Object} 错误信息对象，包含code和message

使用示例 / Examples

响应示例 / Response Examples

const { Ret } = require('mm_ret');

// 成功响应
const success = Ret.body({ message: '操作成功' });
// {"result":{"message":"操作成功"}}

// 错误响应
const error = Ret.error(400, '参数验证失败');
// {"error":{"code":400,"message":"参数验证失败"}}

// 列表响应
const list = Ret.list([{ id: 1, name: '用户1' }, { id: 2, name: '用户2' }], 2);
// {"result":{"list":[{...}],"count":2}}

// 对象响应
const obj = Ret.obj({ id: 1, name: '张三', age: 25 });
// {"result":{"obj":{...}}}

// 布尔响应
const bool = Ret.bl(true, '操作成功');
// {"result":{"bl":true,"tip":"操作成功"}}

请求示例 / Request Examples

const { Req } = require('mm_ret');

// 基本请求
const req = new Req('user');
const request = req.send('getProfile', { userId: 123 });
// {"method":"user.getProfile","params":{"userId":123},"id":"..."}

// 使用模板
const reqWithTemplate = new Req('message');
reqWithTemplate.tpl.message = {
    to_user: '',
    from_user: '',
    content: ''
};
const templateRequest = reqWithTemplate.send('message', { 
    content: 'Hello!',
    media: { title: '重要通知' }
});
// 自动合并模板字段

错误码参考 / Error Codes

标准JSON-RPC错误码

| 错误码 | 说明 | Description | |--------|------|-------------| | -32700 | 格式错误 | Parse error - Not well-formed | | -32701 | 编码不支持 | Parse error - Unsupported encoding | | -32702 | 无效字符 | Parse error - Invalid character for encoding | | -32600 | 无效请求 | Invalid Request - Not conforming to JSON-RPC 2.0 | | -32601 | 方法不存在 | Method not found | | -32602 | 无效参数 | Invalid params | | -32603 | 内部错误 | Internal error | | -32500 | 应用错误 | Application error | | -32400 | 系统错误 | System error | | -32300 | 传输错误 | Transport error |

自定义错误码

| 错误码 | 说明 | Description | |--------|------|-------------| | 10000 | 业务逻辑错误 | Business logic error | | 30000 | 身份验证失败 | Authentication failed | | 40000 | 数据库执行错误 | Database execution error | | 50000 | 服务端执行错误 | Server execution error | | 70000 | 参数不正确 | Invalid parameters |

测试 / Testing

npm test

许可证 / License

ISC License

贡献 / Contributing

欢迎提交 Issue 和 Pull Request！

更新日志 / Changelog

查看 GitHub Releases 获取详细更新信息。