MidwayJS Art Core

一个为 MidwayJS 提供核心功能的扩展包，包含统一响应、异常处理、分页、实体基类等常用功能。

📦 安装

npm install midwayjs-art-core

🚀 快速开始

1. 导入组件

// src/configuration.ts
import { Configuration } from '@midwayjs/core';
import * as koa from '@midwayjs/koa';
import * as validate from '@midwayjs/validate';
import * as art from 'midwayjs-art-core';

@Configuration({
  imports: [
    koa,
    validate,
    art, // 放在最下面
  ],
})
export class MainConfiguration {}

2. 基础配置

// src/config/config.default.ts
export const art = {
  validate: {
    validationOptions: {
      allowUnknown: true, // 允许未定义的参数
    },
  },
};

📋 功能列表

🔧 统一响应格式

BaseController - 提供统一的响应格式

import { BaseController } from 'midwayjs-art-core';

export class UserController extends BaseController {
  async getUser() {
    const user = { id: 1, name: 'John' };
    return this.ok(user);
  }

  async deleteUser() {
    // 某些验证失败
    return this.fail('用户不存在', RESCODE.VALIDATEFAIL);
  }
}

响应格式：

// 成功响应
{
  "code": 0,
  "msg": "success",
  "data": { "id": 1, "name": "John" }
}

// 失败响应
{
  "code": 1002,
  "msg": "用户不存在"
}

⚠️ 异常处理

全局异常过滤器 - 自动捕获并格式化异常

// 已自动配置，无需手动设置
// 任何未捕获的异常都会被格式化为统一响应

自定义异常类：

import {
  CommException,
  ValidateException,
  CoreException,
} from 'midwayjs-art-core';

// 通用异常
throw new CommException('操作失败');

// 验证异常
throw new ValidateException('参数验证失败');

// 核心异常
throw new CoreException('系统错误');

📄 分页功能

BasePageDto - 标准分页参数验证

import { BasePageDto } from 'midwayjs-art-core';

export class UserPageDto extends BasePageDto {
  @ApiProperty({ description: '用户名' })
  name?: string;
}

// 使用
export class UserController {
  async getUserList(@Body() dto: UserPageDto) {
    // dto.pageIndex - 页码（默认1）
    // dto.pageSize - 每页大小（默认10）
    // dto.name - 自定义查询参数
  }
}

🗄️ 数据库实体

BaseEntity - 通用字段基类

import { BaseEntity } from 'midwayjs-art-core';

@Entity('users')
export class User extends BaseEntity {
  @Column()
  name: string;

  // 继承字段：
  // id: number (主键)
  // createTime: Date (创建时间)
  // updateTime: Date (更新时间)
}

🔧 工具函数

FuncUtil - 实用工具函数

import { FuncUtil } from 'midwayjs-art-core';

export class UserService {
  @Inject()
  funcUtil: FuncUtil;

  async processUser() {
    // 时间格式化
    const timeStr = this.funcUtil.formatDate(new Date());

    // 字符串增强功能
    const result = this.funcUtil.enhanceString('hello world');
  }
}

📊 响应码常量

RESCODE & RESMESSAGE - 统一的状态码和消息

import { RESCODE, RESMESSAGE } from 'midwayjs-art-core';

// 可用的响应码
RESCODE.SUCCESS; // 0 - 成功
RESCODE.COMMFAIL; // 1000 - 通用失败
RESCODE.VALIDATEFAIL; // 1002 - 验证失败
RESCODE.COREFAIL; // 1003 - 核心异常

// 对应的消息
RESMESSAGE.SUCCESS; // 'success'
RESMESSAGE.COMMFAIL; // 'comm fail'
RESMESSAGE.VALIDATEFAIL; // 'validate fail'
RESMESSAGE.COREFAIL; // 'core fail'

🎯 完整示例

// src/controller/user.controller.ts
import { Controller, Get, Post, Body } from '@midwayjs/decorator';
import { BaseController, BasePageDto, RESCODE } from 'midwayjs-art-core';

@Controller('/api/user')
export class UserController extends BaseController {
  @Get('/list')
  async getUserList(@Body() dto: BasePageDto) {
    try {
      const users = await this.userService.findUsers(dto);
      return this.ok(users);
    } catch (error) {
      return this.fail('获取用户列表失败', RESCODE.COMMFAIL);
    }
  }

  @Post('/create')
  async createUser(@Body() dto: CreateUserDto) {
    const user = await this.userService.create(dto);
    return this.ok(user);
  }
}