@zenweb/messagecode

ZenWeb 统一消息代码模块，用于消息代码的解析和格式化。

特性

• 📝 统一管理应用中的消息代码
• 🔍 支持消息代码递归查找（a.b.c → a.b → a）
• 📁 支持 JSON 和 JavaScript 文件加载
• 🎯 模板变量替换 {param}
• ⚠️ 便捷的 fail() 方法快速抛出业务异常

安装

npm install @zenweb/messagecode

依赖

本模块是 ZenWeb 框架的内置模块，无需单独安装。

如需在其他项目中独立使用，需配合以下模块：

• @zenweb/core
• @zenweb/inject
• @zenweb/result

快速开始

import { Core } from '@zenweb/core';
import modInject from '@zenweb/inject';
import modResult from '@zenweb/result';
import modMessageCode from '@zenweb/messagecode';

const app = new Core();
app.setup(modInject());
app.setup(modResult());
app.setup(modMessageCode());

配置选项

app.setup(modMessageCode({
  // 手动定义消息代码
  codes: {
    'user.notfound': '用户不存在',
    'user.login.fail': '登录失败: {reason}',
  },
  // 自动加载的消息代码文件（默认: ['./message-codes.json']）
  autoLoadFilenames: ['./message-codes.json', './codes/custom.js'],
}));

使用方法

在控制器中使用

import { Context } from '@zenweb/core';

export class UserController {
  async login(ctx: Context) {
    // 格式化消息
    const message = ctx.messageCodeResolver.format('user.login.fail', { reason: '密码错误' });
    // 输出: '登录失败: 密码错误'

    // 检查消息代码是否存在
    if (ctx.messageCodeResolver.has('user.notfound')) {
      // ...
    }

    // 直接抛出失败异常
    ctx.messageCodeResolver.fail('user.notfound');
  }
}

消息代码文件

JSON 格式 (message-codes.json):

{
  "user.notfound": "用户不存在",
  "user.login.fail": "登录失败: {reason}",
  "error.system": "系统错误"
}

JavaScript 格式 (codes.js):

export default {
  'user.notfound': '用户不存在',
  'user.login.fail': '登录失败: {reason}',
};

递归查找

当使用字符串代码查找时，会按点分隔递归查找父级代码：

// 配置: { 'user': '用户相关错误', 'user.login.fail': '登录失败' }
ctx.messageCodeResolver.get('user.login.fail');     // 返回: '登录失败'
ctx.messageCodeResolver.get('user.login.timeout');  // 返回: '用户相关错误'
ctx.messageCodeResolver.get('other.error');         // 返回: undefined

API 文档

MessageCodeResolver

| 方法 | 说明 | |------|------| | format(code, params?) | 格式化消息，找不到代码时返回代码本身 | | get(code) | 获取消息格式，字符串代码支持递归查找 | | has(code) | 检查消息代码是否存在 | | fail(code, params?) | 解析消息并抛出 ResultFail 异常 | | set(code, message) | 设置单个消息代码 | | assign(codes) | 批量设置消息代码 | | load(filename) | 从文件加载消息代码（支持 .json 和 .js） |

License

MIT