CLI开发工具前端构建构建工具代码生成前端【免费下载链接】angular-cliCLI tool for Angular项目地址https://gitcode.com/gh_mirrors/an/angular-cli点击查看免费下载导读angular-devkit/core是 Angular CLI 生态中所有开发工具包DevKit共用的基础库负责提供跨平台路径处理、虚拟文件系统抽象、JSON Schema 校验、层级日志、工作区workspace读写与字符串/模板工具等底层能力。本文以仓库中由 API Extractor 自动生成的官方 API 报告 goldens/public-api/angular_devkit/core/index.api.md 为骨架逐模块拆解其全部公共导出符号类、接口、函数、类型与命名空间并结合 packages/angular_devkit/core/src 下的真实源码帮助读者理解每个 API 的职责、调用约定与典型应用场景。读完本文你将能够熟练使用这套基础设施开发自己的 Angular 构建工具、Schematics 或 CLI 插件。一、文档性质与整体导出结构index.api.md是 API Extractor 工具自动生成的“API 报告文件”API Report File它精确记录了angular-devkit/core包对外公开的完整 TypeScript 类型签名是理解该包能力边界最权威的索引。报告开头的 import 列表揭示了核心依赖ajvSchema 校验引擎、rxjs响应式流贯穿整个 API、source-map模板源码映射的Position类型。从包入口 packages/angular_devkit/core/src/index.ts 可以看到核心模块按功能域划分为以下命名空间与顶层导出命名空间 / 导出职责virtualFs虚拟文件系统host 抽象、内存实现、装饰器、路径操作json含json.schemaJSON 类型系统与 Schema 校验/转换体系logging基于 rxjs Observable 的层级日志系统workspaces工作区angular.json的读取、建模与写入strings字符串命名转换camelize、dasherize 等tags模板字符串标签函数oneLine、stripIndent 等test测试用虚拟文件系统TestHost顶层函数与类路径工具、BaseException异常体系、PriorityQueue、template模板引擎源码入口通过export *直接透出 exception.ts、json/index.ts、utils/index.ts、virtual-fs/index.ts 的全部符号因此报告中的所有顶层函数如normalize、join都可直接从包根导入。二、路径系统Path类型与路径工具函数Angular DevKit 将“路径”建模为带品牌标记的字符串类型从根本上杜绝了 Unix 风格/与 Windows 风格\混用导致的跨平台 bug。API 报告定义了以下核心类型export type Path string { __PRIVATE_DEVKIT_PATH: void }; export type PathFragment Path { __PRIVATE_DEVKIT_PATH_FRAGMENT: void }; export type PosixPath string { __PRIVATE_DEVKIT_POSIX_PATH: void }; export type WindowsPath string { __PRIVATE_DEVKIT_WINDOWS_PATH: void };这些类型的实现见 packages/angular_devkit/core/src/virtual-fs/path.tsPath是“已被大多数 DevKit 方法识别的规范化路径”PathFragment是单个文件/目录名不带分隔符两个常量NormalizedSep/与NormalizedRoot/分别定义了规范化路径的分隔符与根。2.1 核心路径函数一览API 报告公开的路径函数全部从包根直接导出包括函数签名行为说明normalize(path: string): Path将任意字符串规范化为Path统一分隔符、合并重复分隔符noCacheNormalize(path: string): Path不做缓存的规范化版本避免长驻进程中的路径缓存膨胀resetNormalizeCache(): void清空normalize内部缓存join(p1: Path, ...others: string[]): Path拼接多个路径片段并规范化relative(from: Path, to: Path): Path求相对路径要求两个入参均为绝对路径否则抛出PathMustBeAbsoluteExceptionresolve(p1: Path, p2: Path): Path类似 Nodepath.resolve的规范化解析split(path: Path): PathFragment[]按分隔符切分为片段数组末尾空片段会被剔除basename(path: Path): PathFragment取文件名dirname(path: Path): Path取目录名extname(path: Path): string取扩展名含点号isAbsolute(p: Path): boolean判断是否以/开头fragment(path: string): PathFragment将字符串转换为片段类型getSystemPath(path: Path): string转换为当前操作系统原生路径格式asPosixPath/asWindowsPath(path: Path): PosixPath / WindowsPath显式转换为对应平台格式源码中join的实现path.ts展示了其归一化策略(p1 ? p1 / : ) others.join(/)后交给normalizerelative则先校验绝对性再对两个路径逐段比较公共前缀并回溯..dirname对根目录下的文件如/file做了特判返回/。这些边界处理正是 DevKit 路径 API 比手写字符串操作更可靠的原因。2.2path模板标签报告同时导出一个path: TemplateTagPath允许以 ES6 模板字符串形式构造规范化路径import { path } from angular-devkit/core; const p path/src/${app}/main.ts; // 类型为 Path内容已规范化其实现基于 utils/literals.ts 中的TemplateTag机制与tags命名空间中的oneLine、stripIndent等共用同一套模板标签基础设施。三、虚拟文件系统virtualFs统一一切文件访问virtualFs是angular-devkit/core最有价值的抽象之一它把“文件系统”建模为一个基于 rxjs Observable 的异步接口使同一套业务代码可以透明地运行在真实磁盘、内存、压缩包或测试夹具之上。接口定义见 packages/angular_devkit/core/src/virtual-fs/host/interface.ts。3.1 核心接口ReadonlyHost与Hostinterface ReadonlyHostStatsT extends object {} { readonly capabilities: HostCapabilities; exists(path: Path): Observableboolean; isDirectory(path: Path): Observableboolean; isFile(path: Path): Observableboolean; list(path: Path): ObservablePathFragment[]; read(path: Path): ObservableFileBuffer; stat(path: Path): ObservableStatsStatsT | null | null; } interface HostStatsT extends object {} extends ReadonlyHostStatsT { delete(path: Path): Observablevoid; rename(from: Path, to: Path): Observablevoid; watch(path: Path, options?: HostWatchOptions): ObservableHostWatchEvent | null; write(path: Path, content: FileBufferLike): Observablevoid; }关键设计点文件内容类型FileBuffer即ArrayBufferFileBufferLike为ArrayBufferLike强调二进制安全报告标记为 deprecated 的stringToFileBuffer/fileBufferToString提供了与字符串互转的兼容通道。能力标志HostCapabilities只有一个synchronous: boolean字段用于标注 host 是否支持同步访问这是SyncDelegateHost能否安全包装的判据。监听机制watch返回ObservableHostWatchEvent事件对象携带path、time与typeHostWatchEventType枚举定义了Changed(0)、Created(1)、Deleted(2)、Renamed(3)四种事件类型Renamed作用于原文件路径。HostWatchOptions支持persistent与recursive两个选项。元数据Stats类型在宿主自定义字段基础上混入isFile()、isDirectory()以及size、atime、mtime、ctime、birthtime与 Nodefs.Stats对齐。3.2 内存实现SimpleMemoryHost与TestHostSimpleMemoryHost是纯内存的Host实现内部维护MapPath, StatsSimpleMemoryHostStats缓存所有读写操作exists、isDirectory、isFile、list、read、stat、delete、rename、write、watch均有对应的受保护同步版本_exists、_read等并提供reset()一键清空。SimpleMemoryHostStats携带content: FileBuffer | null与inspect()。TestHost继承SimpleMemoryHost并叠加测试能力构造时可传入{[path: string]: string}初始文件映射$exists、$read、$write等以$前缀的同步便捷方法直接操作字符串内容records/clearRecords()记录每次文件操作的日志TestLogRecord用于断言“读取了哪些文件”files属性列出全部文件sync返回SyncDelegateHost同步视图。它是 modules/testing/builder 等测试基建的核心底座。3.3 装饰器链ResolverHost及其子类ResolverHostT是一个抽象包装类把路径解析逻辑抽成protected abstract _resolve(path: Path): Path子类只需实现路径重写规则即可透明装饰任意底层 hostAliasHost通过_aliases: MapPath, Path实现路径别名get aliases()暴露映射表PatternMatchingHost以正则MapRegExp, ReplacementFunction实现模式替换addPattern(pattern, replacementFn)注册规则ScopedHost以_root: Path将整个 host 限定在某个子目录视野内对外路径自动拼接到 root 下。这三者分别服务于“路径重定向”“批量规则改写”“目录隔离”三类典型场景且全部保持 Observable 异步语义不变。3.4 记录与提交CordHostCordHost命名取自“cord/编目”在内存 host 之上记录所有待执行变更实现“事务式”文件系统变更集合_filesToCreate、_filesToOverwrite、_filesToDelete、_filesToRename/_filesToRenameRevert查询方法willCreate(path)、willOverwrite(path)、willDelete(path)、willRename(path)、willRenameTo(path, to)records(): CordHostRecord[]导出变更清单记录类型为联合类型CordHostCreate | CordHostOverwrite | CordHostRename | CordHostDelete每种都带kind判别字段与path创建/覆盖还带content重命名带from/tocommit(host, force?)将全部记录应用到目标 host返回Observablevoidclone()可复制当前状态。这使 DevKit 可以在“模拟执行”与“真正落盘”之间自由切换与 Schematics 的 Tree 思想一脉相承。3.5 同步适配与工厂SyncDelegateHostT将异步HostT包装为同步接口read返回FileBuffer、write为void内部通过_doSyncCall阻塞等待 Observable 完成若底层 host 不满足capabilities.synchronous相关调用会抛出SynchronousDelegateExpectedException。createSyncHostStatsT(handler: SyncHostHandlerStatsT): HostStatsT反向操作把一组纯同步回调SyncHostHandler全部方法直接返回值而非 Observable适配为异步Host。Empty实现ReadonlyHost的空文件系统一切存在性查询恒为 false。SafeReadonlyHost为ReadonlyHost提供防御性包装避免外部误用可变接口。四、JSON 类型系统与 Schema 校验体系json/json.schemajson命名空间定义了 DevKit 通用的 JSON 值类型json.schema则提供完整的 JSON Schema 编译、校验、提示与转换能力是angular.json、Schematic 选项等所有配置校验的底层引擎。4.1 JSON 值类型export type JsonValue boolean | string | number | JsonArray | JsonObject | null; export interface JsonObject { [prop: string]: JsonValue; } export interface JsonArray extends ArrayJsonValue {}配套的类型守卫isJsonObject(value): value is JsonObject与isJsonArray(value): value is JsonArray可用于安全收窄类型。JsonPointer是带品牌标记的字符串类型string { __PRIVATE_DEVKIT_JSON_POINTER: void }配合buildJsonPointer(fragments)、joinJsonPointer(root, ...others)、parseJsonPointer(pointer)三个函数完成 JSON PointerRFC 6901的构造与解析。4.2CoreSchemaRegistrySchema 注册中心CoreSchemaRegistry implements SchemaRegistry是整套校验体系的中心实现见 packages/angular_devkit/core/src/json/schema/registry.ts。其构造函数默认创建Ajv实例并加载ajv-formats关键成员如下成员说明compile(schema)将JsonSchema编译为PromiseSchemaValidatoraddFormat(format)注册自定义SchemaFormatnameformatter: Format对应 ajv 的 FormataddSmartDefaultProviderT(source, provider)注册“智能默认值”提供者SmartDefaultProvider输入 schema、返回T | ObservableTusePromptProvider(provider)启用交互式提示当 schema 中声明x-prompt时按PromptDefinition收集用户输入useXDeprecatedProvider(onUsage)上报 schema 中x-deprecated标记的使用情况addPreTransform/addPostTransform在编译校验前后注入JsonVisitor转换器支持依赖排序内部用PartiallyOrderedSet管理registerUriHandler(handler)注册$ref外部 URI 的解析器UriHandler失败时回退到内置 HTTP 客户端ɵflatten(schema)展平$ref引用的内部方法4.3 校验器与结果interface SchemaValidator { (data: JsonValue, options?: SchemaValidatorOptions): PromiseSchemaValidatorResult; } interface SchemaValidatorResult { data: JsonValue; errors?: SchemaValidatorError[]; // SchemaValidatorError PartialErrorObject来自 ajv success: boolean; }SchemaValidatorOptions提供applyPreTransforms、applyPostTransforms、withPrompts三个开关可精确控制校验管线。校验失败时抛出SchemaValidationException继承自BaseException其静态方法createMessages(errors)会把 ajv 错误转换为可读消息——源码对additionalProperties关键字会给出“Unknown option xxx. Valid options are: ...”对enum会列出允许值显著提升了 CLI 报错的用户体验。4.4 遍历与合并工具visitJsonContextT(json, visitor, schema?, refResolver?, context?)按 schema 驱动遍历 JSON 树JsonVisitor可返回ObservableJsonValue | JsonValue从而支持异步转换ReferenceResolver负责解析遍历中遇到的$ref。visitJsonSchema(schema, visitor)遍历 schema 自身结构JsonSchemaVisitor收到(current, pointer, parentSchema?, index?)。mergeSchemas(...schemas)合并多个 schema。getTypesOfSchema(schema): Setstring提取 schema 声明的类型集合。transforms命名空间addUndefinedDefaults(value, pointer, schema?)与addUndefinedObjectDefaults为 schema 中声明了default但数据中缺失的属性补填默认值是“智能默认值”的静态实现。PromptDefinition是交互式提示的定义结构id、message、type、propertyTypes、可选default、items普通值或{value, label}对象、multiselect、validator与rawPromptProvider接收定义数组并返回ObservableInput{[id]: JsonValue}将问题与答案映射起来。关于x-prompt的完整约定可参见 docs/specifications/schematic-prompts.md。五、层级日志系统logging基于 Observable 的 Loggerlogging命名空间提供一套可组合、可级联、可变换的日志实现核心类Logger直接继承 rxjs 的ObservableLogEntry实现见 packages/angular_devkit/core/src/logger/logger.ts这意味着日志流天然支持map、filter、merge等所有 rxjs 操作符。5.1 核心类型与等级export type LogLevel debug | info | warn | error | fatal; interface LogEntry extends LoggerMetadata { level: LogLevel; message: string; timestamp: number; } interface LoggerMetadata extends JsonObject { name: string; path: string[]; }Logger构造时通过遍历 parent 链构建path元数据如[root, build]因此每条日志都自带“日志来源层级路径”。LoggerApi接口定义了createChild、log以及debug/info/warn/error/fatal五个等级方法Logger.asApi()返回剥离 Observable 能力的纯接口视图便于在不想暴露订阅能力的场景下传递。5.2 级联与子 LoggercreateChild(name)创建子 Logger子 Logger 的每条日志会自动上抛给父 Logger构造函数中通过订阅父_subject实现最终汇聚到根 Logger——这正是 CLI 中“各模块分别打印、统一采集”架构的基础。forEach(next, promiseCtor?)提供以 Promise 方式遍历日志流的能力。5.3 变换型 Logger类行为IndentLogger构造参数indentation: string每条日志自动加上缩进前缀适合嵌套任务的可视化缩进LevelTransformLogger以(level: LogLevel) LogLevel变换日志等级如把 fatal 降级为 errorLevelCapLogger基于levelMap静态表将日志等级“封顶”到指定上限超限等级被映射为上限等级TransformLogger以(stream: ObservableLogEntry) ObservableLogEntry对流做任意变换是最灵活的扩展点NullLogger丢弃所有日志的无操作实现用于静默模式六、工作区 APIworkspaces读写angular.jsonworkspaces命名空间封装了 Angular 工作区配置文件的建模与读写是 CLI 命令如ng config、ng generate操作angular.json的统一入口。核心实现见 packages/angular_devkit/core/src/workspace/core.ts 与 definitions.ts。6.1 定义模型interface WorkspaceDefinition { readonly extensions: Recordstring, JsonValue | undefined; readonly projects: ProjectDefinitionCollection; } interface ProjectDefinition { readonly extensions: Recordstring, JsonValue | undefined; readonly targets: TargetDefinitionCollection; root: string; prefix?: string; sourceRoot?: string; } interface TargetDefinition { options?: Recordstring, JsonValue | undefined; configurations?: Recordstring, Recordstring, JsonValue | undefined | undefined; defaultConfiguration?: string; builder: string; }ProjectDefinitionCollection与TargetDefinitionCollection均继承内部DefinitionCollectionV一个实现ReadonlyMap的集合其set/delete会触发可选的DefinitionCollectionListenerV监听器——这正是“修改工作区模型 → 自动同步回磁盘”机制的关键。add()方法用于向集合添加定义项目名重复时抛出Project name already exists.见 definitions.ts。6.2 读写流程interface WorkspaceHost { isDirectory(path: string): Promiseboolean; isFile(path: string): Promiseboolean; readFile(path: string): Promisestring; writeFile(path: string, data: string): Promisevoid; } function createWorkspaceHost(host: virtualFs.Host): WorkspaceHost; async function readWorkspace(path: string, host: WorkspaceHost, format?: WorkspaceFormat): Promise{ workspace: WorkspaceDefinition }; function writeWorkspace(workspace: WorkspaceDefinition, host: WorkspaceHost, path?: string, format?: WorkspaceFormat): Promisevoid;WorkspaceFormat目前只有JSON一种取值。createWorkspaceHost把virtualFs.Host适配为基于 Promise 的WorkspaceHost实现“虚拟文件系统 ←→ 工作区读写”的桥接。readWorkspace的行为见 core.ts若传入的是目录则在其中查找已知工作区文件——目前仅angular.json与.angular.json找不到时报错Unable to locate a workspace file...若传入的是文件则根据文件名推断格式最终委托readJsonWorkspace解析并将格式记录在formatLookupWeakMap 中供writeWorkspace复用。仓库中 packages/angular_devkit/core/src/workspace/json/test/cases 目录下的大量 JSON 用例AddProject1.json、ProjectAddTarget.json、ArrayPush.json等验证了工作区修改的各种边界场景可作为理解数据模型变化的参考。七、字符串、模板与通用工具7.1strings命名风格转换strings命名空间提供 CLI 领域高频使用的命名转换函数实现见 packages/angular_devkit/core/src/utils/strings.ts其行为在源码注释中有明确示例函数示例decamelize(str)innerHTML→inner_htmldasherize(str)innerHTML→inner-htmlaction_name→action-namecamelize(str)将-、_、.、空格后的字符大写classify(str)首字母大写的 camelize用于生成类名underscore(str)innerHTML→inner_h_t_m_l基于/([a-z\d])([A-Z])/g规则capitalize(str)首字母大写levenshtein(a, b)计算编辑距离CLI 中用于“您是不是想输入 xxx”的拼写建议7.2tags模板字符串标签oneLine(strings, ...values)将多行模板字符串合并为单行stripIndent/stripIndents去除公共缩进indentBy(indentations)生成按指定空格数缩进的标签函数trimNewlines去除首尾空行。7.3template模板编译引擎templateT(content, options?): (input: T) string将字符串编译为带类型参数T的渲染函数配合templateParser(sourceText, fileName): TemplateAst与TemplateAst*系列节点类型TemplateAstContent、TemplateAstEvaluate、TemplateAstComment、TemplateAstEscape、TemplateAstInterpolate使用。TemplateOptions支持fileName、module、sourceMap、sourceRoot、sourceURL。这是 Schematics 中.template文件渲染机制的底层实现例如 packages/schematics/angular/component/files 下的模板即由它驱动。7.4 其他通用结构PriorityQueueT二叉堆式优先队列提供push、pop、peek、clear、toArray、size构造时传入比较器(x, y) number。PartiallyOrderedSetTdeprecated带依赖关系的偏序集合add(item, deps?)支持声明依赖并在出现循环时抛出CircularDependencyFoundException已逐步被替换但仍被CoreSchemaRegistry的 visitor 排序内部使用。deepCopyTdeprecated通用深拷贝工具。isPromise(obj)deprecatedPromise 类型守卫已被更现代的判断方式取代。八、异常体系BaseException与派生异常报告顶部与各模块中散布的异常类统一继承自BaseException extends Error定义见 packages/angular_devkit/core/src/exception.ts构成一棵清晰的异常树通用UnknownException携带自定义消息、CircularDependencyFoundException、DependencyNotFoundException路径相关InvalidPathException、PathCannotBeFragmentException、PathIsDirectoryException、PathIsFileException、PathMustBeAbsoluteException以及文件相关FileDoesNotExistException、FileAlreadyExistExceptionSchema 相关SchemaValidationException见 registry.ts同步适配相关SynchronousDelegateExpectedException。BaseException目前仅是对Error的薄封装各派生类在构造时生成面向用户的友好消息如Path x does not exist.CLI 层通过统一的异常处理流程将这些消息呈现给用户。九、典型应用场景总结综合以上模块angular-devkit/core在仓库内的典型协作方式是CLI 命令层如 packages/angular/cli/src/commands使用workspaces.readWorkspace读取工作区模型通过ProjectDefinitionCollection/TargetDefinitionCollection增删改项目与 target构建与生成逻辑使用virtualFs.Host抽象访问文件真实环境用磁盘 host测试环境用TestHost用CordHost实现变更暂存与提交所有配置angular.json、schema.json经CoreSchemaRegistry编译校验缺失选项由addSmartDefaultProvider补默认值、usePromptProvider在交互模式下向用户提问命令行输出经Logger层级体系逐级上抛、统一采集与格式化生成文件的命名组件名、类名、选择器由strings命名转换函数完成跨平台路径由normalize、join、relative等PathAPI 保证一致性。从 API 报告 index.api.md 到各模块源码virtual-fs、json/schema、logger、workspace、utilsangular-devkit/core始终贯彻“小而稳、可组合、响应式”的设计哲学。对于希望扩展 Angular CLI 或开发 Schematics 工具的开发者而言这份公共 API 就是最重要的开发地图。赞分享CLI开发工具前端构建构建工具代码生成前端【免费下载链接】angular-cliCLI tool for Angular项目地址https://gitcode.com/gh_mirrors/an/angular-cli点击查看免费下载相关推荐GitHub Copilot Hooks 编写指南从配置到脚本契约的完整实战GitHub Copilot Hooks 编写指南从配置到脚本契约的完整实战 Hooks 是 GitHub Copilot 在会话生命周期关键节点触发的 小型CLI开发工具前端构建构建工具代码生成前端Angular Material Core 公共 API 全解析angular/material/core 的核心基础设施与扩展指南Angular Material Core 公共 API 全解析angular/material/core 的核心基础设施与扩展指南 angular/ma前端UI组件设计系统4步把电视盒子变成家庭K歌房TVBoxOSC 卡拉OK功能上手指南4步把电视盒子变成家庭K歌房TVBoxOSC 卡拉OK功能上手指南 想邀朋友来家里唱歌又不想花钱订KTV包厢你手边的电视盒子就能派上用场。TVBoxOSCCLI开发工具前端构建构建工具代码生成前端上一篇如何用Type Helper优化DTOPartialType、PickType、OmitType实战下一篇Lockbox安全最佳实践防止数据泄露与长度分析攻击创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考