MidwayJS 基础组件 - 集成公司基础服务能力

@cicctencent/midwayjs-base 是一个基于 MidwayJS 框架的企业级基础组件，集成了公司常用的基础服务能力，包括认证授权、文件存储、API 网关、会话管理等功能。

• JWT Token 认证
• 单点登录 (SSO) 集成
• 接口权限守卫
• 管理员账号验证

• 腾讯云 COS 文件上传/下载
• 文件访问 URL 生成（带临时签名）
• 多存储桶配置支持

• 统一 API 响应格式
• 请求参数校验
• IP 白名单控制
• API Token 验证

• 分布式会话存储
• 会话超时配置
• 自定义会话服务接口

• 请求检测中间件
• 异常过滤器
• 404 处理
• 统一错误处理

npm install @cicctencent/midwayjs-base

在 src/configuration.ts 中引入配置：

import { Configuration } from '@midwayjs/core';
import * as base from '@cicctencent/midwayjs-base';

@Configuration({
  imports: [
    base
  ],
  importConfigs: [
    // 你的配置
  ]
})
export class MainConfiguration {
  // 配置
}

创建 .env 文件：

# 应用配置
APP_ID=1001
SERVICE_NAME=your-service-name

# API 配置
API_KEY=your-api-key

# SSO 配置
SSO_URL=https://sso.example.com

# 腾讯云配置
TENCENT_CREDENTIAL_SECRETID=your-secret-id
TENCENT_CREDENTIAL_SECRETKEY=your-secret-key

# 会话配置
SESSION_TIMEOUT=1200000

# 日志配置
LOG_LEVEL=info

继承 BaseService 获取基础能力：

import { Provide } from '@midwayjs/core';
import { BaseService } from '@cicctencent/midwayjs-base';
import { GetUserInfoReq, GetUserInfoRes } from '@fefeding/common/dist/models/user/request';

@Provide()
export class UserService extends BaseService {
  async getUserInfo(userId: number) {
    // 检查是否为管理员
    const isManager = await this.checkManager();
    
    // 方式1：使用请求对象
    const req = new GetUserInfoReq();
    req.userId = userId;
    const result = await this.requestBaseApi<GetUserInfoRes>(req);
    
    // 方式2：使用 URL 路径
    // const result = await this.requestBaseApi('/api/user/getInfo', {
    //   data: { userId }
    // });
    
    return result?.data || null;
  }
}

继承 ISessionService 实现会话管理：

import { Provide, Scope, ScopeEnum, Config, Inject } from '@midwayjs/core';
import { ISessionService, TencentService } from '@cicctencent/midwayjs-base';
import { Session, GetLoginSessionReq } from '@fefeding/common/dist/models/account/session';

@Provide('session:service')
@Scope(ScopeEnum.Request, { allowDowngrade: true })
export class SessionService extends ISessionService { 
    @Config('loginOption')
    loginOption: any;

    @Inject()
    tencentService: TencentService;

    async getLoginSession(id: string): Promise<Session> {
        const req = new GetLoginSessionReq();
        req.id = id;
        const res = await this.requestBaseApi(req);
        return res?.data || null;
    }

    async logout(id: string): Promise<any> {
        // 实现登出逻辑
        this.ctx.currentSession = null;
        return { success: true };
    }

    async loginByCode(code: string): Promise<Session> {
        const res = await this.requestBaseApi('/api/session/loginByAuthCode', {
            data: { code }
        });
        return res?.data || null;
    }
}

继承 BaseController：

import { Controller, Get } from '@midwayjs/core';
import { BaseController, CheckLogin } from '@cicctencent/midwayjs-base';

@Controller('/api/user')
export class UserController extends BaseController {
  
  @Get('/info')
  @CheckLogin() // 需要登录态
  async getUserInfo() {
    // 获取当前会话信息
    const session = this.ctx.currentSession;
    
    return this.success({
      userId: session.userId,
      account: session.account
    });
  }
}

使用 TencentService 进行文件操作：

import { Provide, Inject } from '@midwayjs/core';
import { TencentService } from '@cicctencent/midwayjs-base';

@Provide()
export class FileService {
  
  @Inject()
  tencentService: TencentService;
  
  async uploadFile(filePath: string, key: string) {
    // 上传文件到 COS
    const result = await this.tencentService.uploadCosFile(key, filePath);
    
    // 获取文件访问 URL
    const fileUrl = await this.tencentService.getCosFileUrl(key);
    
    return {
      ...result,
      url: fileUrl
    };
  }
}

import { utils, jwt } from '@cicctencent/midwayjs-base';

// 生成 JWT Token
const token = jwt.encodeJWT({ userId: 123 }, 'secret-key');

// 解码 JWT Token
const payload = jwt.decodeJWT(token, 'secret-key');

// 常用工具函数
const isEmail = utils.isEmail('test@example.com');
const timestamp = utils.getTimestamp();

// config/config.default.ts
export default {
  // API 配置
  apiOption: {
    key: 'your-api-key',
    reg: /^\/([^/]+\/)?api\//i,
    ignore: ['/']
  },
  
  // IP 白名单
  ipOption: {
    whiteList: ['127.0.0.1', '::1']
  },
  
  // 会话配置
  session: {
    timeout: 1200000,
    secretKey: 'your-secret-key'
  },
  
  // 认证配置
  auth: {
    ignores: ['/api/test/']
  },
  
  // 基础服务配置
  baseService: {
    manager: ['admin'],
    appId: 1001,
    url: 'https://base-service.example.com'
  }
}

1. RequestInitMiddleware: 请求初始化，设置请求 ID 等
2. DetectMiddleware: 请求检测，获取客户端信息
3. ApiResultFormatterMiddleware: 统一 API 响应格式

1. ApiGuard: API 接口守卫，验证 API Token
2. AuthGuard: 认证守卫，验证登录态

实现 ISessionService 接口来自定义会话管理：

import { Provide } from '@midwayjs/core';
import { ISessionService } from '@cicctencent/midwayjs-base';

@Provide()
export class CustomSessionService implements ISessionService {
  async getLoginSession(token: string) {
    // 自定义会话获取逻辑
    return session;
  }
  
  async loginByCode(authCode: string) {
    // 自定义登录逻辑
    return session;
  }
}

组件内置了统一的异常过滤器，支持自定义错误处理。

npm run build

npm test

npm run lint
npm run lint:fix

当前版本: 1.0.35

如有问题或建议，请联系开发团队。

MIT License