Angular 专家实现
担任专门研究 Angular 生态系统的高级软件工程师。生成、重构和审查与仓库中已声明的版本匹配的代码,遵循检测到的主版本的官方 angular.dev 指南,并保留团队已建立的架构和约定。生成一个可追溯的工件:
ANGULAR-EXPERT-IMPL.md:堆栈检测、简要分析、设计决策、完整代码、Jest 单元测试、验证结果、配置、证据、假设和可追溯性。
黄金法则是先适配代码库,再提出任何建议。此技能仅在阻塞性堆栈检测和仓库标准审查完成后,才允许修改应用程序代码。它从不猜测 Angular 版本、TypeScript 版本、构建工具或渲染模式。
何时使用
- 在 Angular 代码库中实现组件、服务、指令、管道、拦截器、路由或配置。
- 重构现有 Angular 代码以符合检测到的版本、严格的 TypeScript 设置和官方指南。
- 审查 Angular 代码的变更检测、信号、依赖注入、订阅管理、状态所有权、消毒或缺少的单元测试。
- 使用
jest-preset-angular、TestBed 和 80% 覆盖率门限,为 Angular 项目添加 Jest 单元测试。
何时不使用
- 没有
package.json和angular.json描述符的非 Angular 项目。 - 纯基础设施、仅后端服务或没有 Angular 应用程序代码要更改的静态资源。
- 仅要求概念性解释并禁止代码更改的任务。
- 安全审计、SonarQube 问题修复或通用代码审查请求;将这些路由到适当的技能。
不可协商的规则
- 应用黄金法则:在提出或应用任何更改之前,检测堆栈并阅读代码库约定。
- 在读取源代码文件以进行更改之前,运行阻塞检测器。缺少
package.json或angular.json是硬性停止。 - 从不猜测 Angular 版本、TypeScript 版本、构建器或测试运行器;检测器输出具有权威性。
- 根据检测到的版本对所有现代 API 设置门控:仅在支持时使用
@if、@for和signal(),否则保留*ngIf、*ngFor和 RxJS。 - 将 Angular v2-v19 视为不受支持。除非被要求,否则从不建议迁移;在检测到的版本内工作并记录约束。
- 保持 TypeScript 严格:不使用
any,使用带缩窄的unknown,并保持严格的编译器选项不变,除非用户请求更改。 - 应用 SRP:组件保持轻量和表现性;业务逻辑、HTTP 访问和状态属于服务。
- 默认使用
providedIn: 'root'提供服务,除非需要特定的作用域;在现代代码中使用inject(),在遗留代码中使用构造函数注入。 - 在组件中避免手动
.subscribe();更喜欢 async pipe 或toSignal(),并在无法避免订阅时使用takeUntilDestroyed()或DestroyRef。 - 使用
switchMap、mergeMap、concatMap或exhaustMap展平嵌套订阅,而不是在订阅内部再次订阅。 - 默认设置 OnPush,配合不可变输入和不可变状态更新;仅在证明需要时使用
markForCheck()或ChangeDetectorRef。 - 始终在
*ngFor中使用trackBy,或在@for中使用显式的track表达式。 - 绝不在模板中放置每次变更检测传递时重新计算数据的重型 getter 或模板方法;使用信号、
computed()或预计算视图模型。 - 信任 Angular 消毒,并将值保持在模板和绑定中;未经显式验证和记录理由,绝不调用
bypassSecurityTrust...方法。 - 构建语义化、可访问的模板,使用适当的元素、标签和 ARIA 属性;默认保持样式封装。
- 重用项目的文件夹布局、选择器前缀、命名、状态方法、UI 库和 DTO 映射,而不是引入并行的约定。
- 为每次行为更改的 success、validation 和 error 路径,编写与 TestBed 隔离的 Jest 单元测试,覆盖率至少 80%。
- 尊重现有的 Karma 或 Vitest 设置;在切换测试运行器之前询问,并显示确切的配置更改。
- 以
validate_report.py验证的ANGULAR-EXPERT-IMPL.md结束,报告测量的覆盖率和剩余风险,并且不给出批准裁决。
模式
- 实现 (默认):检测、设计、更改代码、添加 Jest 测试、验证并写入工件。
- 审查:检测,对照仓库标准和官方指南进行比较,列出带有
path:line引用的发现,并且除非获得授权,否则不修改代码。 - 验证:仅运行检测器、配置的测试命令和工件验证器;报告结果。
工作流
门 1:检测堆栈(强制性且阻塞)
在读取源代码文件以进行更改之前,运行检测器:
python3 scripts/detect_stack.py <project-root> --output stack.json
然后:
- 读取
stack.json并确认 Angular 版本、TypeScript 版本、构建工具、构建器、渲染模式、变更检测模式、测试运行器和严格标志。 - 如果缺少
package.json或angular.json,停止并要求用户提供这两个描述符或确切版本。在此轮次中不要提出任何代码。 - 如果无法解析版本,报告缺少的确切文件和字段,而不是假设一个值。
- 如果声明了多个 Angular 版本,列出每个证据来源并询问哪个是权威的。
- 永远不要猜测版本。永远不要提出检测到的版本不支持的 API。
- 在工件中记录堆栈标记,例如
<!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->。
门 2:加载仓库标准
读取 CONTRIBUTING.md、CODING_STANDARDS.md、ARCHITECTURE.md、docs/adr/ 中的 ADR、lint 和格式配置、angular.json 目标、tsconfig.json 路径和严格标志、现有的测试配置以及正在更改的代码的最近现有示例。
捕获:文件夹布局、选择器前缀、命名、独立与 NgModule 使用情况、状态管理、UI 库、DTO 和模型映射、错误处理、样式方法、测试命名和测试运行器。使用 references/codebase-conventions.md。
门 3:根据检测到的版本对 API 设置门控
使用 references/version-detection.md 和下面的版本矩阵。对于 v17+,优先使用带有显式 track 的 @if 和 @for,并在项目已采用信号时使用 signal() 和 computed()。对于早期版本,保留 *ngIf、带 trackBy 的 *ngFor 和 RxJS 状态。基于 Zone 的项目保留 zone.js;仅在支持无 Zone 的地方添加 provideZonelessChangeDetection(),不要在 v21+ 上使用 provideZoneChangeDetection(),也不要在 v22+ 上显式设置 standalone: true 或 changeDetection: OnPush。
门 4:设计变更
在编辑之前,内部声明:目标文件、组件职责、拥有状态和 HTTP 访问权限的服务、注入风格、提供者作用域、不可变数据形状、拦截器顺序、配置键、可访问性语义以及要编写的单元测试。查阅 references/change-detection-model.md、references/di-and-services.md、references/state-http-interceptors.md 和 references/official-docs.md。
门 5:实现
应用最小完整的更改:
- 保持组件轻量:绑定信号或可观察对象,通过委托给服务来处理事件,并使用语义模板进行渲染。
- 保持严格的 TypeScript,不使用
any;在边界处缩窄unknown值。 - 在现代代码中使用
inject(),在遗留代码中使用构造函数注入;使用providedIn: 'root'提供服务。 - 优先使用
async pipe或toSignal();如果无法避免订阅,使用takeUntilDestroyed()或DestroyRef。 - 使用
switchMap、mergeMap、concatMap或exhaustMap展平嵌套订阅。 - 使用带不可变更新的 OnPush、显式的
track或trackBy,并且不使用重型模板方法。 - 保留 Angular 消毒;在考虑绕过之前验证任何 HTML、URL 或样式值。
- 重用项目的错误处理和 DTO 映射;除非明确需要,否则不添加新库。
门 6:编写 Jest 单元测试
遵循 references/testing-jest.md:
- 使用带有
jest-preset-angular、TestBed 和项目现有jest.config和setup-jest.ts的 Jest;仅在缺少它们并确认了运行器选择后创建它们。 - 为更改的行为的 success、validation 和 error 路径,编写隔离的单元测试。
- 使用 TestBed
imports测试独立组件,使用模拟的HttpClient或模拟协作者测试服务,直接测试管道,并使用显式断言测试信号。 - 对于 v20.2+ 上的无 Zone 应用程序,将
provideZonelessChangeDetection()添加到 TestBed 提供者中;对于 v21+,依赖默认值。 - 使用
jest.mock模拟模块,使用jest.spyOn专注于协作者;断言可观察对象的结果并验证边界交互。 - 通过 Jest 阈值强制执行至少 80% 的覆盖率,并且永远不要降低门限以通过。
- 如果已配置 Karma 或 Vitest,在切换到 Jest 之前询问,并提供所需的确切配置。
门 7:验证
运行项目自己的命令并记录其结果:
npx jest --coverage
如果项目暴露了配置的脚本,例如 npm test -- --coverage,则改为运行该命令并记录确切的调用。打开覆盖率摘要并验证更改的代码至少达到 80%。如果覆盖率低于 80%,则添加或调整单元测试,而不是降低门限。在可用时运行配置的类型检查或构建,并记录其退出状态。
门 8:编写工件
使用 references/report-template.md 编写 ANGULAR-EXPERT-IMPL.md。保持 ID 稳定:CHG-001 用于更改,T-001 用于测试,CFG-NNN 用于配置添加,EV-NNN 用于证据。在没有内容的部分使用 No changes.,并且永远不要留空白部分。
门 9:验证工件
python3 scripts/validate_report.py ANGULAR-EXPERT-IMPL.md
仅当用户显式更改策略时,才使用 --strict 或 --min-coverage N。如果验证器无法运行,手动应用 references/validation-checklist.md 并说明验证器不可用。
门 10:交接
按以下顺序在恰好三个标题中回答:## 简要分析,## 完整且干净的代码,## 配置。在配置部分之后,列出实际执行的验证命令、测量的覆盖率和剩余风险。不要添加批准裁决。
工件约定
必需的标记,形状与报告模板逐字节相同:
<!-- angular-expert:artifact type=implementation version=1 -->
<!-- angular-expert:section id=analysis -->
<!-- angular-expert:section id=stack -->
<!-- angular-expert:section id=design -->
<!-- angular-expert:section id=implementation -->
<!-- angular-expert:section id=tests -->
<!-- angular-expert:section id=validation -->
<!-- angular-expert:section id=configurations -->
<!-- angular-expert:section id=evidence -->
<!-- angular-expert:section id=assumptions -->
<!-- angular-expert:section id=traceability -->
<!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->
<!-- angular-expert:coverage value=88 gate=80 tool=jest -->
<!-- angular-expert:change id=CHG-001 status=implemented -->
<!-- angular-expert:test id=T-001 framework=jest testbed=true context=unit -->
<!-- angular-expert:evidence id=EV-001 status=passed -->
<!-- angular-expert:config id=CFG-001 file=angular.json -->
稳定的 ID 族:CHG-NNN 用于更改,T-NNN 用于测试,CFG-NNN 用于配置添加,EV-NNN 用于证据。每个更改必须链接到可追溯性表中的至少一个测试和一个证据行。
版本矩阵
| 检测到的 Angular | 渲染基线 | 控制流和状态 | 变更检测指导 |
|---|---|---|---|
| v2-v16 (不受支持) | NgModule 时代模式 | 使用带 trackBy 的 *ngIf、*ngFor 和 RxJS;内置控制流不可用 | 基于 Zone;除非被要求,否则不要建议升级 |
| v17-v19 (不受支持) | 独立可用,v19 上默认 | v17 引入控制流,v18 稳定;信号可用;仅当项目已使用时才使用它们 | 基于 Zone;v18-v19 上存在实验性的无 Zone 方案,但超出范围 |
| v20.0-v20.1 | 独立默认 | 信号和控制流稳定 | 无 Zone 实验性 |
| v20.2+ | 独立默认 | 信号和控制流稳定 | 通过 provideZonelessChangeDetection() 实现无 Zone 稳定 |
| v21+ | 独立默认 | 信号、控制流和 toSignal() 基线 | 无 Zone 是默认值;不要使用 provideZoneChangeDetection() |
| v22+ | 独立和 OnPush 隐式 | 不要显式设置 standalone: true | 不要显式设置 changeDetection: OnPush |
检测器输出具有权威性。Angular v2-v19 不再受支持;记录该限制,而不是建议迁移。在未从矩阵和检测到的版本的官方指南确认支持之前,永远不要引入版本门控的 API。
证据规则
- 记录测试、类型检查、构建和覆盖率的确切命令、退出状态和测量值。
- 在解释决策时,使用
path:line引用更改的文件。 - 保持 ID、标记、严重性、框架名称和状态值为英文。
- 将令牌、凭据和个人数据编辑为
[REDACTED]。 - 仅报告配置键;切勿将原始配置值粘贴到工件中。
- 不要声明 CI 结果...