# @eggjs/tegg-controller-plugin 中文文档 规范地址：https://npmcn.com/package/%40eggjs/tegg-controller-plugin/ 版本：3\.88\.1 npm 元数据更新时间：2026-09-08T07:59:56.522Z 中文译文更新时间：2026-11-14T03:43:38.128Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40eggjs/tegg-controller-plugin 原文对照：https://npmcn.com/package/%40eggjs/tegg-controller-plugin/?lang=original 项目主页：https://github.com/eggjs/tegg 源码仓库：https://github.com/eggjs/tegg ## 关键信息（来自 npm 元数据） - 包体积（解压后）：318 kB，62 个文件 - TypeScript 类型：包内自带 - Node.js 要求：\>=14\.0\.0 - 运行依赖：20 个 - 首次发布：2021-07-22T08:53:28.390Z - 最新版本发布：2026-09-08T07:59:56.352Z - 近 30 天下载量：2360（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：261（近 12 个月 71 个） ## 中文简介 鸡蛋的控制器 ## 安装 ```sh npm install @eggjs/tegg-controller-plugin ``` 也可以使用：`pnpm add @eggjs/tegg-controller-plugin`、`yarn add @eggjs/tegg-controller-plugin`、`bun add @eggjs/tegg-controller-plugin` ## README # @eggjs/tegg-controller-plugin 使用注解的方式来开发 egg 中的 Controller ## Install ```shell # tegg 注解 npm i --save @eggjs/tegg # tegg 插件 npm i --save @eggjs/tegg-plugin # tegg controller 插件 npm i --save @eggjs/tegg-controller-plugin ``` ## Prepare ```json // tsconfig.json { "extends": "@eggjs/tsconfig" } ``` ## Config ```js // config/plugin.js exports.tegg = { package: '@eggjs/tegg-plugin', enable: true, }; exports.teggController = { package: '@eggjs/tegg-controller-plugin', enable: true, }; ``` ## Usage ### Middleware Middleware 支持多个入参，依次传入要生效的中间件 中间件注解，可以添加在类/方法上。添加在类上时，对类上所有方法生效，添加在方法上时，只对当前方法生效。 ```ts // app/middleware/global_log.ts import { Context } from 'egg'; import type { Next } from '@eggjs/controller-decorator'; export default async function globalLog(ctx: Context, next: Next) { ctx.logger.info('have a request'); return next(); } export default async function globalLog2(ctx: Context, next: Next) { ctx.logger.info('have a request2'); return next(); } // app/controller/FooController.ts import { Middleware } from '@eggjs/tegg'; @Middleware(globalLog,globalLog2) export class FooController { @Middleware(methodCount) async hello() { } } ``` ### Context 当需要 egg context 时，可以使用 `@Context` 注解来声明。 ```ts // app/controller/FooController.ts import { Context, EggContext } from '@eggjs/tegg'; export class FooController { @Middleware(methodCount) async hello(@Context() ctx: EggContext) { } } ``` ### HTTP 注解 #### HTTPController/HTTPMethod `@HTTPController` 注解用来声明当前类是一个 HTTP controller，可以配置路径前缀。 `@HTTPMethod` 注解用来声明当前方法是一个 HTTP method，只有带了这个注解，HTTP 方法才会被暴露出去，可以配置方法路径， ```ts // app/controller/FooController.ts import { Context, EggContext, HTTPController, HTTPMethod, HTTPMethodEnum } from '@eggjs/tegg'; @HTTPController({ path: '/foo', }) export class FooController { @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/hello', }) async hello() { } } ``` #### Param HTTP 协议中有各种各样的传参方式，比如 query,path,body 等等。 ##### HTTPBody 接收 body 参数 ```ts // app/controller/FooController.ts import { Context, EggContext, HTTPController, HTTPMethod, HTTPMethodEnum, HTTPBody } from '@eggjs/tegg'; @HTTPController({ path: '/foo', }) export class FooController { @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/hello', }) async hello(@HTTPBody() name: string) { return `hello, ${name}`; } } ``` ##### HTTPQuery/HTTPQueries 两者的区别在于参数是否为数组， HTTPQuery 只会取第一个参数，HTTPQueries 只提供数组形式。 HTTPQuery 的参数类型只能是 string, HTTPQueries 的参数类型只能是 string\[\]。 ```ts // app/controller/FooController.ts import { Context, EggContext, HTTPController, HTTPMethod, HTTPMethodEnum, HTTPQuery, HTTPQueries } from '@eggjs/tegg'; @HTTPController({ path: '/foo', }) export class FooController { @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/hello', }) async hello( // /foo/hello?name=bar // HTTPQuery: name=bar // HTTPQueries: name=[bar] @HTTPQuery() name: string, @HTTPQueries() names: string[], ) { return `hello, ${name}`; } } ``` 如果需要使用别名，比如说 query 中的 name 不能在 js 中声明时，如 foo\[bar\] 这类的。可以通过以下形式 ```ts @HTTPQuery({ name: 'foo[bar]' }) fooBar: string, ``` ##### HTTPParam 接收 path 中的参数，类型只能为 string ```ts // app/controller/FooController.ts import { Context, EggContext, HTTPController, HTTPMethod, HTTPMethodEnum, HTTPBody } from '@eggjs/tegg'; @HTTPController({ path: '/foo', }) export class FooController { @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/:id', }) async hello(@HTTPParam() id: string) { return `hello, ${name}`; } } ``` 如果需要使用别名，比如说 path 中使用正则声明 `/foo/(.*)`, 可以通过以下形式 ```ts // 具体 name 值可以查看 path-to-regexp @HTTPParam({ name: '0' }) id: string ``` ### Host Host 注解，用于指定 HTTP 方法仅在 host 匹配时执行。 可以添加在类/方法上。添加在类上时，对类上所有方法生效，添加在方法上时，只对当前方法生效。方法上的注解可以覆盖类上的注解 ```ts // app/controller/FooController.ts import { Host } from '@eggjs/tegg'; @Host('foo.eggjs.com') export class FooController { // 仅能通过 foo.eggjs.com 访问 async hello() { } // 仅能通过 bar.eggjs.com 访问 @Host('bar.eggjs.com') async bar() { } } ``` ### MCP 注解 #### MCPController/MCPPrompt/MCPTool/MCPResource `@MCPController` 注解用来声明当前类是一个 MCP controller。 通过使用装饰器 `@MCPPrompt` `@MCPTool` `@MCPResource` 来声明对应的 MCP 类型。 使用 `@ToolArgsSchema` `@PromptArgsSchema` `@Extra` 来 schema 和 extra。 ```ts import { MCPController, PromptArgs, ToolArgs, MCPPromptResponse, MCPToolResponse, MCPResourceResponse, MCPPrompt, MCPTool, MCPResource, PromptArgsSchema, Logger, Inject, ToolArgsSchema, } from '@eggjs/tegg'; import { z } from '@eggjs/tegg/zod'; export const PromptType = { name: z.string(), }; export const ToolType = { name: z.string().describe('npm package name'), }; export const ToolOutputType = { packageName: z.string(), found: z.boolean(), }; @MCPController() export class McpController { @Inject() logger: Logger; @MCPPrompt() async foo(@PromptArgsSchema(PromptType) args: PromptArgs): Promise { this.logger.info('hello world'); return { messages: [ { role: 'user', content: { type: 'text', text: `Generate a concise but descriptive commit message for these changes:\n\n${args.name}`, }, }, ], }; } @MCPTool({ outputSchema: ToolOutputType }) async bar(@ToolArgsSchema(ToolType) args: ToolArgs): Promise> { const output = { packageName: args.name, found: false, }; return { content: [ { type: 'text', text: `npm package: ${args.name} not found`, }, ], structuredContent: output, }; } @MCPResource({ template: [ 'mcp://npm/{name}{?version}', { list: () => { return { resources: [ { name: 'egg', uri: 'mcp://npm/egg?version=4.10.0' }, { name: 'mcp', uri: 'mcp://npm/mcp?version=0.10.0' }, ], }; }, }, ], }) async car(uri: URL): Promise { return { contents: [{ uri: uri.toString(), text: 'MOCK TEXT', }], }; } } ``` #### MCP 地址 MCP controller 完整的实现了 SSE / streamable HTTP / streamable stateless HTTP 三种模式，默认情况下，他们的路径分别是 `/mcp/init` `/mcp/stream` `/mcp/stateless/stream`, 你可以根据你所需要的场景，灵活使用对应的接口。 ```ts // config.{env}.ts import { randomUUID } from 'node:crypto'; export default () => { const config = { mcp: { sseInitPath: '/mcp/init', // SSE path sseMessagePath: '/mcp/message', // SSE message path streamPath: '/mcp/stream', // streamable path statelessStreamPath: '/mcp/stateless/stream', // stateless streamable path sessionIdGenerator: randomUUID, }, }; return config; }; ``` ## 常见问题 ### @eggjs/tegg-controller-plugin 是什么？ 鸡蛋的控制器 ### 如何安装 @eggjs/tegg-controller-plugin？ 在项目目录运行 npm install @eggjs/tegg-controller-plugin，或使用 pnpm add / yarn add / bun add。 ### @eggjs/tegg-controller-plugin 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @eggjs/tegg-controller-plugin 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=14\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @eggjs/tegg-controller-plugin 可以商用吗？ @eggjs/tegg-controller-plugin 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @eggjs/tegg-controller-plugin 的下载量有多少？ 根据 npm 官方下载统计，@eggjs/tegg-controller-plugin 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,360 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @eggjs/tegg-controller-plugin 还在维护吗？ 最新版本 3\.88\.1 发布于 2026/09/08（2 个月前）；至今共发布 261 个版本，其中过去 12 个月发布了 71 个；首次发布于 2021/07/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。