ios-chaos-monkey

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Chaos Monkey — Crash-Hunter Best Practices

iOS Chaos Monkey — 崩溃排查最佳实践

Adversarial crash-hunting guide for iOS and Swift applications. Contains 47 rules across 8 categories, prioritized by crash severity. Every rule follows TDD: dangerous code first, a failing test that proves the bug, then the fix that makes the test pass.

这是一份针对iOS和Swift应用的对抗式崩溃排查指南。包含8个分类下的47条规则，按崩溃严重程度排序。每条规则均遵循TDD流程：先展示危险代码，再给出可证明问题的失败测试，最后提供能让测试通过的修复方案。

When to Apply

适用场景

Reference these guidelines when:

Hunting data races, deadlocks, and concurrency crashes in Swift
Auditing memory management for retain cycles and use-after-free
Reviewing async/await code for cancellation and continuation leaks
Stress-testing file I/O and CoreData/SwiftData persistence layers
Writing proof-of-crash tests before implementing fixes

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

排查Swift中的数据竞争、死锁及并发崩溃问题
审计内存管理，排查循环引用和野指针问题
检查async/await代码中的取消逻辑和续体泄漏问题
对文件I/O和CoreData/SwiftData持久化层进行压力测试
在实现修复前编写可复现崩溃的测试用例

Rule Categories by Priority

按优先级划分的规则分类


race-
mem-
dead-
async-
io-
mut-
exhaust-
objc-

Priority	Category	Impact	Prefix
1	Data Races & Thread Safety	CRITICAL	`race-`
2	Memory Corruption & Leaks	CRITICAL	`mem-`
3	Deadlocks & Thread Starvation	HIGH	`dead-`
4	Async/Await & Structured Concurrency	HIGH	`async-`
5	File I/O & Persistence Corruption	MEDIUM-HIGH	`io-`
6	Collection & State Mutation	MEDIUM	`mut-`
7	Resource Exhaustion	MEDIUM	`exhaust-`
8	Objective-C Interop Traps	LOW-MEDIUM	`objc-`


race-
mem-
dead-
async-
io-
mut-
exhaust-
objc-

优先级	分类	影响等级	前缀
1	数据竞争与线程安全	严重（CRITICAL）	`race-`
2	内存损坏与泄漏	严重（CRITICAL）	`mem-`
3	死锁与线程饥饿	高（HIGH）	`dead-`
4	Async/Await与结构化并发	高（HIGH）	`async-`
5	文件I/O与持久化损坏	中高（MEDIUM-HIGH）	`io-`
6	集合与状态修改	中（MEDIUM）	`mut-`
7	资源耗尽	中（MEDIUM）	`exhaust-`
8	Objective-C互操作陷阱	中低（LOW-MEDIUM）	`objc-`

Quick Reference

快速参考

1. Data Races & Thread Safety (CRITICAL)

1. 数据竞争与线程安全（严重）

```
race-dictionary-concurrent-write
```
- Concurrent Dictionary mutation crashes with EXC_BAD_ACCESS
```
race-array-concurrent-append
```
- Concurrent Array append corrupts internal buffer
```
race-property-access
```
- Unsynchronized property read-write across threads
```
race-lazy-initialization
```
- Lazy property double-initialization under concurrency
```
race-singleton-initialization
```
- Non-atomic singleton exposes partially constructed state
```
race-bool-flag
```
- Non-atomic Bool flag creates check-then-act race
```
race-closure-capture-mutation
```
- Closure captures mutable reference across threads
```
race-delegate-nilification
```
- Delegate set to nil during active callback

```
race-dictionary-concurrent-write
```
- 并发修改Dictionary会导致EXC_BAD_ACCESS崩溃
```
race-array-concurrent-append
```
- 并发向Array添加元素会破坏内部缓冲区
```
race-property-access
```
- 跨线程未同步的属性读写操作
```
race-lazy-initialization
```
- 并发场景下懒加载属性的重复初始化问题
```
race-singleton-initialization
```
- 非原子性单例暴露部分构造完成的状态
```
race-bool-flag
```
- 非原子性Bool标志引发的检查-执行竞争问题
```
race-closure-capture-mutation
```
- 闭包在跨线程场景下捕获可变引用
```
race-delegate-nilification
```
- 回调执行期间将Delegate设为nil

2. Memory Corruption & Leaks (CRITICAL)

2. 内存损坏与泄漏（严重）

```
mem-closure-retain-cycle
```
- Strong self capture in escaping closures creates retain cycle
```
mem-timer-retain-cycle
```
- Timer retains target creating undiscoverable retain cycle
```
mem-delegate-strong-reference
```
- Strong delegate reference prevents deallocation
```
mem-unowned-crash
```
- Unowned reference crashes after owner deallocation
```
mem-notification-observer-leak
```
- NotificationCenter observer retains closure after removal needed
```
mem-combine-sink-retain
```
- Combine sink retains self without cancellable storage
```
mem-async-task-self-capture
```
- Task captures self extending lifetime beyond expected scope

```
mem-closure-retain-cycle
```
- 逃逸闭包中强引用self导致循环引用
```
mem-timer-retain-cycle
```
- Timer持有目标对象导致难以发现的循环引用
```
mem-delegate-strong-reference
```
- 强引用Delegate导致对象无法释放
```
mem-unowned-crash
```
- 无主引用在宿主对象释放后引发崩溃
```
mem-notification-observer-leak
```
- NotificationCenter观察者未移除导致闭包泄漏
```
mem-combine-sink-retain
```
- Combine Sink强引用self且未存储取消句柄
```
mem-async-task-self-capture
```
- Task捕获self导致对象生命周期超出预期范围

3. Deadlocks & Thread Starvation (HIGH)

3. 死锁与线程饥饿（高）

```
dead-sync-on-main
```
- DispatchQueue.main.sync from main thread deadlocks instantly
```
dead-recursive-lock
```
- Recursive lock acquisition on same serial queue
```
dead-actor-reentrancy
```
- Actor reentrancy produces unexpected interleaving
```
dead-semaphore-in-async
```
- Semaphore.wait() inside async context deadlocks thread pool
```
dead-queue-hierarchy
```
- Dispatch queue target hierarchy inversion deadlocks
```
dead-mainactor-blocking
```
- Blocking MainActor with synchronous heavy work

```
dead-sync-on-main
```
- 在主线程调用DispatchQueue.main.sync会立即引发死锁
```
dead-recursive-lock
```
- 在同一串行队列上递归获取锁
```
dead-actor-reentrancy
```
- Actor重入导致意外的执行交错
```
dead-semaphore-in-async
```
- 在异步上下文调用Semaphore.wait()会导致线程池死锁
```
dead-queue-hierarchy
```
- 调度队列目标层级反转引发死锁
```
dead-mainactor-blocking
```
- 用同步重操作阻塞MainActor

4. Async/Await & Structured Concurrency (HIGH)

4. Async/Await与结构化并发（高）

```
async-missing-cancellation
```
- Missing Task.isCancelled check wastes resources after navigation
```
async-detached-task-leak
```
- Detached task without cancellation handle leaks work
```
async-task-group-error
```
- TaskGroup silently drops child task errors
```
async-continuation-leak
```
- CheckedContinuation never resumed leaks awaiting task
```
async-actor-hop-starvation
```
- Excessive MainActor hops in hot loop starve UI updates
```
async-unsafe-sendable
```
- @unchecked Sendable hides data race from compiler

```
async-missing-cancellation
```
- 缺少Task.isCancelled检查导致页面跳转后资源浪费
```
async-detached-task-leak
```
- 未持有取消句柄的Detached Task导致任务泄漏
```
async-task-group-error
```
- TaskGroup会静默丢弃子任务错误
```
async-continuation-leak
```
- CheckedContinuation从未恢复导致等待任务泄漏
```
async-actor-hop-starvation
```
- 热循环中过度切换MainActor导致UI更新停滞
```
async-unsafe-sendable
```
- @unchecked Sendable会向编译器隐藏数据竞争问题

5. File I/O & Persistence Corruption (MEDIUM-HIGH)

5. 文件I/O与持久化损坏（中高）

```
io-concurrent-file-write
```
- Concurrent file writes corrupt data without coordination
```
io-coredata-cross-thread
```
- CoreData NSManagedObject accessed from wrong thread
```
io-swiftdata-background
```
- SwiftData model accessed from wrong ModelContext
```
io-plist-concurrent-mutation
```
- UserDefaults concurrent read-write produces stale values
```
io-filemanager-race
```
- FileManager existence check then use is a TOCTOU race
```
io-keychain-thread-safety
```
- Keychain access from multiple threads returns unexpected errors

```
io-concurrent-file-write
```
- 无协调的并发文件写入会导致数据损坏
```
io-coredata-cross-thread
```
- 在错误线程访问CoreData的NSManagedObject
```
io-swiftdata-background
```
- 在错误的ModelContext中访问SwiftData模型
```
io-plist-concurrent-mutation
```
- UserDefaults的并发读写会产生过期值
```
io-filemanager-race
```
- FileManager的存在性检查后使用存在TOCTOU竞争问题
```
io-keychain-thread-safety
```
- 多线程访问Keychain会返回意外错误

6. Collection & State Mutation (MEDIUM)

6. 集合与状态修改（中）

```
mut-enumerate-and-mutate
```
- Collection mutation during enumeration crashes at runtime
```
mut-kvo-dealloc-crash
```
- KVO observer not removed before deallocation crashes
```
mut-index-out-of-bounds
```
- Array index access without bounds check crashes
```
mut-force-unwrap
```
- Force unwrapping optional in production crashes on nil
```
mut-enum-future-cases
```
- Non-exhaustive switch crashes on unknown enum case

```
mut-enumerate-and-mutate
```
- 枚举期间修改集合会在运行时崩溃
```
mut-kvo-dealloc-crash
```
- 释放前未移除KVO观察者会引发崩溃
```
mut-index-out-of-bounds
```
- 未做边界检查的数组索引访问会崩溃
```
mut-force-unwrap
```
- 生产环境中强制解包可选值会在nil时崩溃
```
mut-enum-future-cases
```
- 非穷举switch会在遇到未知枚举case时崩溃

7. Resource Exhaustion (MEDIUM)

7. 资源耗尽（中）

```
exhaust-unbounded-task-spawn
```
- Unbounded task spawning in loop exhausts memory
```
exhaust-thread-explosion
```
- GCD creates unbounded threads under concurrent load
```
exhaust-urlsession-leak
```
- URLSession not invalidated leaks delegate and connections
```
exhaust-file-descriptor-leak
```
- File handle not closed leaks file descriptors
```
exhaust-memory-warning-ignored
```
- Low memory warning ignored triggers Jetsam kill

```
exhaust-unbounded-task-spawn
```
- 循环中无限制创建任务会耗尽内存
```
exhaust-thread-explosion
```
- 并发负载下GCD会创建无限制线程
```
exhaust-urlsession-leak
```
- URLSession未失效会导致代理和连接泄漏
```
exhaust-file-descriptor-leak
```
- 文件句柄未关闭会导致文件描述符泄漏
```
exhaust-memory-warning-ignored
```
- 忽略低内存警告会触发Jetsam终止

8. Objective-C Interop Traps (LOW-MEDIUM)

8. Objective-C互操作陷阱（中低）

```
objc-unrecognized-selector
```
- Missing @objc annotation crashes with unrecognized selector
```
objc-nsnull-in-json
```
- NSNull in decoded JSON collection crashes on access
```
objc-bridge-type-mismatch
```
- Swift/ObjC bridge type mismatch crashes at runtime
```
objc-dynamic-dispatch
```
- Missing dynamic keyword breaks method swizzling

```
objc-unrecognized-selector
```
- 缺少@objc注解会引发未识别选择器崩溃
```
objc-nsnull-in-json
```
- 解码后的JSON集合中包含NSNull会在访问时崩溃
```
objc-bridge-type-mismatch
```
- Swift/ObjC桥接类型不匹配会在运行时崩溃
```
objc-dynamic-dispatch
```
- 缺少dynamic关键字会破坏方法交换

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 分类结构与影响等级说明
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	分类定义与排序规则
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息