FUNC - 轻量类型化 CLI 框架

API 参考

本页是当前 func 核心 API 和 funcgo 支持命令的紧凑参考。行为细节见核心概念、字段选项、参数注入和错误处理。

命令

签名	结构	描述
`@Command(params: CommandParams)`	`CommandParams = { name: string, description?: string, alias?: string }`	注册具名命令。name 或 alias 会与第一个输入 token 匹配。
`@Handler(params?: HandlerParams)`	`HandlerParams = { flag?: string, alias?: string, description?: string, path?: string[] }`	注册默认处理器、标志处理器或路径处理器。path 不能与 flag 或 alias 同时使用。
`@SubOptions(params: Array<OptionParams>)`	`OptionParams = { name: string, type?: Boolean \| String \| Number \| [String], description?: string, alias?: string }`	为当前命令作用域添加仅用于解析的选项。需要从命令实例读取值时，优先使用字段选项。
`@CommandMissing()`	`-`	注册用于处理未知首个裸输入的 fallback command。它可以像普通命令一样定义 handler 和字段选项。
`@CommandMajor()`	`-`	注册空调用和顶层选项使用的主命令。
`@Catch()`	`-`	注册局部命令错误方法。它会先于全局错误处理器运行。
`@CatchAll() / @CommandError()`	`-`	注册全局错误处理器类。CommandError 是 CatchAll 的别名。

字段选项和校验器

签名	结构	描述
`@Flag(params?)`	`params = { name?: string, alias?: string, description?: string }`	声明一个赋值给被装饰属性的布尔选项。
`@Value(params?)`	`params = { name?: string, alias?: string, description?: string, type?: Boolean \| String \| Number \| [String], required?: boolean }`	声明标量值选项。能从 design metadata 推断类型时会自动推断。
`@ArrayValue(params?)`	`params = { name?: string, alias?: string, description?: string }`	声明重复字符串选项，并以字符串数组赋给属性。
`@Required()`	`-`	要求选项被显式提供，或拥有已定义的值。
`@Enum(values)`	`values = Array<boolean \| string \| number>`	校验标量值或数组中的每一项是否位于允许列表中。
`@DependsOn(options)`	`options = string[]`	当此选项被显式提供时，要求同时提供其他选项。
`@Exclusive(options)`	`options = string[]`	拒绝此选项与列表中的任一选项同时显式出现。
`@ValueValidate(fn)`	`fn(value, options) => boolean \| string \| void`	运行自定义校验器。返回 false 或字符串会创建校验错误。

上下文注入

签名	描述
`@Args()`	注入 FuncArgs：命令元数据、选中的处理器、inputs、path、归一化 option 和原生解析数据。
`@Regs()`	注入 CommandRegistry，用于读取已注册命令元数据。
`@Exception()`	向局部 catch 方法和全局错误处理器注入 FuncException。

应用

签名	结构	描述
`@FuncModule(params)`	`params = { commands?: Class[], imports?: FuncModuleInput[], services?: Class[] }`	创建应用模块或功能模块。
`@Service()`	`-`	标记一个可被注入到命令或其他已注册服务中的服务类。
`run(input, options?)`	`options = { argv?: string[], services?: Class[] }`	创建应用并执行。
`createApp(input, options?)`	`options = { argv?: string[], services?: Class[] }`	创建底层 Container，但不运行它。

运行时类型

签名	结构	描述
`FuncArgs`	`{ command?, handler?, inputs: string[], native, option: UserOption, path: string[] }`	由 Args 注入的归一化运行时上下文。
`FuncException`	`code, details, error, level, message, type, preventDefaultPrint()`	catch 和错误处理器使用的 FuncError 包装对象。
`CommandRegistry`	`{ commands: RegisterCommandParams[] }`	由 Regs 注入的只读注册表上下文。

支持命令

funcgo 为 func 项目提供标准开发和构建命令。完整流程见工具链。

签名	结构	描述
`funcgo setup`	`--fix?`	检查 package.json，并建议缺失的 func.entry、func.outDir、bin、dev script 和 build script 配置。
`funcgo dev`	`-f, --file <entry>; -- <args>`	通过本地 TypeScript 运行时执行项目入口，并把参数透传给命令。
`funcgo build`	`-f, --file <entry>; -o, --out <dir>; -e, --external <package>`	为生产环境打包项目入口，输出到 func.outDir 或 dist，并创建可执行 bin.js。

配置

funcgo setup --fix 可以自动写入推荐项目配置。

签名	描述
`package.json#func.entry`	funcgo dev 和 funcgo build 在未提供 --file 时使用的默认 TypeScript 入口文件。
`package.json#func.outDir`	funcgo build 在未提供 --out 时使用的默认构建输出目录。