koa-boot-runtime

基于 Koa 3 + Prisma + tsoa 的 AI 驱动全栈框架运行时核心包：Prisma 客户端工厂、约定配置（分页 / 响应 / 认证白名单）、核心中间件、AI 工具注册表。

设计原则：框架只做机制（framework），业务与系统模块归项目。 14 个系统模块（用户 / 角色 / 菜单 / 字典等）已下沉到脚手架模板（生成于项目 src/system/，可改可删），不再内置在 runtime。

通常由脚手架 create-koa-boot 生成项目时自动引入，也可手动集成到现有 Koa 项目。

特性

• 约定配置（Convention）：分页参数名/默认值、统一响应格式（成功码 200 可改 'S'、字段名）、认证白名单——全部可定制，框架提供默认值
• Prisma 客户端工厂：统一创建客户端，开发环境自动启用 SQL 日志
• 核心中间件：errorHandler / requestLogger / authMiddleware（JWT）/ validateRequest；依赖系统表的 operationLogger / permissionMiddleware 随系统模块下沉到项目
• AI 工具注册表：aiToolRegistry 供 AI 代理注册/发现工具
• 类型与工具子路径：common/*（响应/分页工厂）、utils/*（jwt/crypto/oss/redis 等）、config/*

安装

npm install koa-boot-runtime

快速开始

import Koa from 'koa';
import Router from '@koa/router';
import { createPrismaClient, middlewares, configureRuntime } from 'koa-boot-runtime';

// 1. 覆盖约定配置（可选，默认值已可用）：
configureRuntime({
  response: { successCode: 'S' },          // 成功码改为字符串 'S'
  pagination: { pageSizeField: 'size' },   // 每页条数参数名改为 size
});

const app = new Koa();
const router = new Router();

app.use(middlewares.errorHandler);
app.use(middlewares.requestLogger);
app.use(middlewares.authMiddleware);
// 项目内 tsoa 生成的路由（系统 + 业务）：
// RegisterRoutes(router);
app.use(router.routes()).use(router.allowedMethods());

// 全局共享 Prisma 客户端
app.context.db = createPrismaClient();

app.listen(3003);

约定配置（Convention）

框架的可定制约定统一收敛到 configureRuntime()，不传的项沿用默认值，改配置即可全局生效（success/fail/pageSuccess/resolvePagination/authMiddleware 均实时读取）：

import { configureRuntime } from 'koa-boot-runtime';

configureRuntime({
  response: {
    codeField: 'code',              // 响应状态码字段名
    messageField: 'message',        // 响应消息字段名
    dataField: 'data',              // 响应数据字段名
    successCode: 200,               // 成功码（数字或字符串，如 'S'）
    successMessage: '操作成功',      // success() 默认成功消息
    failCode: -1,                   // 失败码
  },
  pagination: {
    pageField: 'page',              // 请求页码字段名
    pageSizeField: 'pageSize',      // 请求每页条数字段名
    defaultPage: 1,                 // 默认页码
    defaultPageSize: 10,            // 默认每页条数
    maxPageSize: 100,               // 每页条数上限
    listField: 'list',              // 响应列表字段名
    metaField: 'pagination',        // 响应分页元数据字段名
  },
  auth: {
    whitelist: ['/api-docs', '/docs', '/swagger.json'],  // 公开路径前缀（追加；框架默认端点常驻放行）
    whitelistPatterns: [],          // 公开路径正则（追加）
  },
});

• configureRuntime() 可多次调用、与当前约定增量合并（后传覆盖先传的同名字段），适合按模块分散配置；
• auth.whitelist / auth.whitelistPatterns 为追加语义：/api-docs、/docs、/swagger.json 等框架自带公开端点常驻放行，项目只需追加业务公开路径（如登录），不会因配置而失效。

响应/分页的类型声明在生成项目的 src/common/types.ts（tsoa 硬约束不解析 node_modules 类型），字段名与成功码按默认约定声明；定制字段名后类型描述与实际输出以运行时为准。

Public API

包入口仅导出以下命名（其余内部模块不导出）：

import { createPrismaClient, configureRuntime, getConvention, aiToolRegistry, middlewares, types } from 'koa-boot-runtime';

| 导出 | 说明 | | --- | --- | | createPrismaClient() | Prisma 客户端工厂（开发环境启用 SQL 日志） | | configureRuntime(opts?) | 覆盖/追加约定配置（多次调用增量合并；auth 白名单为追加语义） | | getConvention() | 读取当前约定配置 | | aiToolRegistry | AI 工具注册表（registerAiTool / listToolDefs / getAiTool） | | middlewares | errorHandler / requestLogger / authMiddleware / validateRequest | | types | 响应/分页类型、decorators、paginateQuery、normalizeDto |

白名单子路径可解：koa-boot-runtime/common/*、koa-boot-runtime/utils/*、koa-boot-runtime/config/*。

环境要求

• Node.js >= 18.19
• MySQL 8.x（运行时数据）
• Redis（可选，缺失时自动降级）

相关

• 脚手架：create-koa-boot（npx create-koa-boot 交互式创建，或 npx create-koa-boot my-app --example 生成完整三端示例工程）