angular-best-practices-v20

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Angular Best Practices (v20+)

Angular最佳实践（v20+）

Comprehensive performance optimization guide for Angular 20+ applications with modern features like Signals, httpResource, signal inputs/outputs, @defer blocks, and native control flow syntax. Contains 35+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

这是针对Angular 20+应用的全面性能优化指南，涵盖Signals、httpResource、signal输入/输出、@defer块和原生控制流语法等现代特性。包含8个类别下的35+条规则，按影响优先级排序，可指导自动化重构和代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new Angular 20+ components
Using Signals for reactive state (signal, computed, linkedSignal, effect)
Using httpResource/resource for data fetching
Using signal inputs/outputs instead of decorators
Implementing @defer for lazy loading
Using native control flow (@if, @for, @switch)
Implementing SSR with incremental hydration
Reviewing code for performance issues

在以下场景中可参考本指南：

编写新的Angular 20+组件
使用Signals实现响应式状态（signal、computed、linkedSignal、effect）
使用httpResource/resource进行数据获取
使用signal输入/输出替代装饰器
实现@defer懒加载
使用原生控制流（@if、@for、@switch）
结合增量 hydration实现SSR
评审代码以排查性能问题

Key Features (v20+)

核心特性（v20+）

Signals - Fine-grained reactivity (signal, computed, linkedSignal, effect)
httpResource - Signal-based HTTP with automatic loading states
Signal inputs/outputs - input(), output() replacing decorators
@defer - Template-level lazy loading with hydration triggers
@for / @if - Native control flow with required track
Standalone by default - No standalone: true needed
Host bindings - host object instead of @HostBinding decorators
Functional interceptors - Simpler HTTP interceptors
takeUntilDestroyed - Built-in subscription cleanup
Incremental hydration - @defer (hydrate on ...) for SSR

Signals - 细粒度响应式能力（signal、computed、linkedSignal、effect）
httpResource - 基于Signal的HTTP请求，自带自动加载状态
Signal输入/输出 - 使用input()、output()替代装饰器
@defer - 模板级懒加载，支持 hydration触发条件
@for / @if - 原生控制流，强制要求track属性
默认独立组件 - 无需设置standalone: true
Host绑定 - 使用host对象替代@HostBinding装饰器
函数式拦截器 - 更简洁的HTTP拦截器
takeUntilDestroyed - 内置的订阅清理机制
增量 hydration - 结合@defer (hydrate on ...)实现SSR

Rule Categories by Priority

按优先级划分的规则类别


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

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	`ssr-`


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

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

Quick Reference

快速参考

1. Change Detection (CRITICAL)

1. 变更检测（关键）

```
change-signals
```
- Use Signals instead of BehaviorSubject 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
```
component-signal-io
```
- Use signal inputs/outputs instead of @Input/@Output decorators
```
signal-computed-pure
```
- Keep computed() pure, no side effects
```
signal-effect-patterns
```
- Use effect() correctly, avoid anti-patterns
```
signal-linkedsignal
```
- Use linkedSignal for derived + writable state

```
change-signals
```
- 使用Signals替代BehaviorSubject实现响应式状态
```
change-onpush
```
- 使用OnPush变更检测策略
```
change-detach-reattach
```
- 在执行重型操作时分离变更检测器
```
change-run-outside-zone
```
- 在NgZone之外执行非UI相关代码
```
component-signal-io
```
- 使用signal输入/输出替代@Input/@Output装饰器
```
signal-computed-pure
```
- 保持computed()的纯函数特性，避免副作用
```
signal-effect-patterns
```
- 正确使用effect()，避免反模式
```
signal-linkedsignal
```
- 使用linkedSignal实现可写的派生状态

2. Bundle & Lazy Loading (CRITICAL)

2. 包与懒加载（关键）

```
bundle-standalone
```
- Use standalone components (default in v20+)
```
bundle-lazy-routes
```
- Lazy load routes with loadComponent/loadChildren
```
bundle-defer
```
- Use @defer blocks for heavy components
```
bundle-preload
```
- Preload routes on hover/focus for perceived speed
```
bundle-no-barrel-imports
```
- Avoid barrel files, use direct imports

```
bundle-standalone
```
- 使用独立组件（v20+默认支持）
```
bundle-lazy-routes
```
- 使用loadComponent/loadChildren实现路由懒加载
```
bundle-defer
```
- 为重型组件使用@defer块
```
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 takeUntilDestroyed for automatic 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
```
- 使用takeUntilDestroyed实现自动订阅清理
```
rxjs-share-replay
```
- 共享可观察对象以避免重复请求
```
rxjs-operators
```
- 使用高效的RxJS操作符
```
rxjs-mapping-operators
```
- 使用正确的映射操作符（switchMap vs exhaustMap）
```
rxjs-no-nested-subscribe
```
- 避免嵌套订阅

4. Template Performance (HIGH)

4. 模板性能（高）

```
template-trackby
```
- Use track function in @for loops (required in v20+)
```
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
```
- 在@for循环中使用track函数（v20+强制要求）
```
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
```
directive-host-composition
```
- Use hostDirectives for composition

```
di-provided-in-root
```
- 对单例服务使用providedIn: 'root'
```
di-injection-token
```
- 对非类依赖使用InjectionToken
```
di-factory-providers
```
- 使用工厂提供者处理复杂初始化逻辑
```
directive-host-composition
```
- 使用hostDirectives实现组合

6. HTTP & Caching (MEDIUM)

6. HTTP与缓存（中）

```
http-resource
```
- Use httpResource/resource for signal-based data fetching
```
http-interceptors
```
- Use functional interceptors for cross-cutting concerns
```
http-transfer-state
```
- Use TransferState for SSR hydration
```
routing-signal-inputs
```
- Use signal-based route inputs

```
http-resource
```
- 使用httpResource/resource实现基于Signal的数据获取
```
http-interceptors
```
- 使用函数式拦截器处理横切关注点
```
http-transfer-state
```
- 使用TransferState实现SSR hydration
```
routing-signal-inputs
```
- 使用基于Signal的路由输入

7. Forms Optimization (MEDIUM)

7. 表单优化（中）

```
forms-reactive
```
- Use reactive forms with typed FormGroup

```
forms-reactive
```
- 使用带类型的FormGroup实现响应式表单

8. General Performance (LOW-MEDIUM)

8. 通用性能（中低）

```
ssr-hydration
```
- Use incremental hydration with @defer (hydrate on ...)
```
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

```
ssr-hydration
```
- 结合@defer (hydrate on ...)实现增量 hydration
```
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-signals.md
rules/bundle-defer.md
rules/http-resource.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-signals.md
rules/bundle-defer.md
rules/http-resource.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外背景信息和参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有规则详细内容的完整指南，请参考：

AGENTS.md