angular-best-practices-legacy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Angular Best Practices (Legacy: v12-16)

Angular最佳实践（旧版本：v12-16）

Comprehensive performance optimization guide for Angular 12-16 applications using NgModule-based architecture and RxJS-centric patterns. Contains 30+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

针对采用NgModule架构和RxJS核心模式的Angular 12-16应用的综合性能优化指南。包含8大类共30+条规则，按影响优先级排序，可用于指导自动化重构和代码生成。

When to Apply

适用场景

Reference these guidelines when:

Maintaining Angular 12-16 codebases
Using NgModule-based architecture
Working with *ngIf, *ngFor directives
Using RxJS for state management
Using class-based HTTP interceptors
Reviewing code for performance issues

当你遇到以下情况时可参考本指南：

维护Angular 12-16代码库
使用基于NgModule的架构
处理*ngIf、*ngFor指令
使用RxJS做状态管理
使用基于类的HTTP拦截器
排查代码性能问题

Key Patterns (v12-16)

核心模式（v12-16）

NgModules - Feature modules for organization
BehaviorSubject - Reactive state management
Subject + takeUntil - Subscription cleanup pattern
Class-based interceptors - HTTP handling with implements HttpInterceptor
**ngFor / ngIf - Structural directives with trackBy
loadChildren - Module-based lazy loading

NgModules - 用特性模块做代码组织
BehaviorSubject - 响应式状态管理
Subject + takeUntil - 订阅清理模式
基于类的拦截器 - 实现HttpInterceptor接口来处理HTTP请求
**ngFor / ngIf - 搭配trackBy使用的结构型指令
loadChildren - 基于模块的懒加载

Rule Categories by Priority

按优先级排序的规则分类


change-
bundle-
rxjs-
template-
di-
http-
forms-
perf-

Priority	Category	Impact	Prefix
1	Change Detection	CRITICAL	`change-`
2	Bundle & Lazy Loading	CRITICAL	`bundle-`
3	RxJS Optimization	HIGH	`rxjs-`
4	Template Performance	HIGH	`template-`
5	Dependency Injection	MEDIUM-HIGH	`di-`
6	HTTP & Caching	MEDIUM	`http-`
7	Forms Optimization	MEDIUM	`forms-`
8	General Performance	LOW-MEDIUM	`perf-`


change-
bundle-
rxjs-
template-
di-
http-
forms-
perf-

优先级	分类	影响程度	前缀
1	变更检测	紧急	`change-`
2	包体积与懒加载	紧急	`bundle-`
3	RxJS优化	高	`rxjs-`
4	模板性能	高	`template-`
5	依赖注入	中高	`di-`
6	HTTP与缓存	中	`http-`
7	表单优化	中	`forms-`
8	通用性能	中低	`perf-`

Quick Reference

快速参考

1. Change Detection (CRITICAL)

1. 变更检测（紧急）

```
change-rxjs-state
```
- Use BehaviorSubject with OnPush for reactive state
```
change-onpush
```
- Use OnPush change detection strategy
```
change-detach-reattach
```
- Detach change detector for heavy operations
```
change-run-outside-zone
```
- Run non-UI code outside NgZone

```
change-rxjs-state
```
- 搭配OnPush策略使用BehaviorSubject实现响应式状态
```
change-onpush
```
- 使用OnPush变更检测策略
```
change-detach-reattach
```
- 执行重负载操作前分离变更检测器
```
change-run-outside-zone
```
- 在NgZone外运行非UI相关代码

2. Bundle & Lazy Loading (CRITICAL)

2. 包体积与懒加载（紧急）

```
bundle-ngmodule
```
- Organize code into feature NgModules
```
bundle-scam
```
- Use Single Component Angular Modules pattern
```
bundle-lazy-routes
```
- Lazy load routes with loadChildren
```
bundle-preload
```
- Preload routes for perceived speed
```
bundle-no-barrel-imports
```
- Avoid barrel files, use direct imports

```
bundle-ngmodule
```
- 将代码组织为特性NgModules
```
bundle-scam
```
- 使用单组件Angular模块（SCAM）模式
```
bundle-lazy-routes
```
- 用loadChildren实现路由懒加载
```
bundle-preload
```
- 预加载路由提升感知速度
```
bundle-no-barrel-imports
```
- 避免桶文件，使用直接导入

3. RxJS Optimization (HIGH)

3. RxJS优化（高）

```
rxjs-async-pipe
```
- Use async pipe instead of manual subscriptions
```
rxjs-takeuntil
```
- Use takeUntil with destroy$ Subject for cleanup
```
rxjs-share-replay
```
- Share observables to avoid duplicate requests
```
rxjs-operators
```
- Use efficient RxJS operators
```
rxjs-mapping-operators
```
- Use correct mapping operators (switchMap vs exhaustMap)
```
rxjs-no-nested-subscribe
```
- Avoid nested subscriptions

```
rxjs-async-pipe
```
- 使用async管道替代手动订阅
```
rxjs-takeuntil
```
- 搭配destroy$ Subject使用takeUntil做订阅清理
```
rxjs-share-replay
```
- 共享observable避免重复请求
```
rxjs-operators
```
- 使用高效的RxJS操作符
```
rxjs-mapping-operators
```
- 使用正确的映射操作符（switchMap vs exhaustMap）
```
rxjs-no-nested-subscribe
```
- 避免嵌套订阅

4. Template Performance (HIGH)

4. 模板性能（高）

```
template-trackby
```
- Use trackBy function with *ngFor
```
template-pure-pipes
```
- Use pure pipes for expensive transformations
```
template-ng-optimized-image
```
- Use NgOptimizedImage for image optimization
```
template-no-function-calls
```
- Avoid function calls in templates
```
template-virtual-scroll
```
- Use virtual scrolling for large lists

```
template-trackby
```
- *ngFor搭配trackBy函数使用
```
template-pure-pipes
```
- 对耗时转换使用纯管道
```
template-ng-optimized-image
```
- 使用NgOptimizedImage做图片优化
```
template-no-function-calls
```
- 避免在模板中调用函数
```
template-virtual-scroll
```
- 长列表使用虚拟滚动

5. Dependency Injection (MEDIUM-HIGH)

5. 依赖注入（中高）

```
di-provided-in-root
```
- Use providedIn: 'root' for singleton services
```
di-injection-token
```
- Use InjectionToken for non-class dependencies
```
di-factory-providers
```
- Use factory providers for complex initialization

```
di-provided-in-root
```
- 单例服务使用providedIn: 'root'
```
di-injection-token
```
- 非类依赖使用InjectionToken
```
di-factory-providers
```
- 复杂初始化使用工厂提供者

6. HTTP & Caching (MEDIUM)

6. HTTP与缓存（中）

```
http-interceptors
```
- Use class-based interceptors for cross-cutting concerns
```
http-transfer-state
```
- Use TransferState for SSR hydration

```
http-interceptors
```
- 用基于类的拦截器处理横切关注点
```
http-transfer-state
```
- SSR hydration使用TransferState

7. Forms Optimization (MEDIUM)

7. 表单优化（中）

```
forms-reactive
```
- Use reactive forms instead of template-driven
```
forms-typed
```
- Use typed FormGroup for type safety

```
forms-reactive
```
- 使用响应式表单替代模板驱动表单
```
forms-typed
```
- 使用带类型的FormGroup保障类型安全

8. General Performance (LOW-MEDIUM)

8. 通用性能（中低）

```
perf-memory-leaks
```
- Prevent memory leaks (timers, listeners, subscriptions)
```
perf-web-workers
```
- Offload heavy computation to Web Workers
```
arch-smart-dumb-components
```
- Use Smart/Dumb component pattern

```
perf-memory-leaks
```
- 预防内存泄漏（定时器、监听器、订阅）
```
perf-web-workers
```
- 将重负载计算任务转移到Web Workers
```
arch-smart-dumb-components
```
- 使用聪明/木偶组件模式

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/change-rxjs-state.md
rules/bundle-ngmodule.md
rules/rxjs-takeuntil.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单独的规则文件获取详细说明和代码示例：

rules/change-rxjs-state.md
rules/bundle-ngmodule.md
rules/rxjs-takeuntil.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外上下文和参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需包含所有展开规则的完整指南，请查看：

AGENTS.md