staff-level-elixir

Staff-Level Elixir

为 BEAM 上的 Elixir 提炼的资深工程师级判断——Elixir、OTP、Ecto 和 Phoenix 会带来哪些设计决策，以及经验丰富的工程师如何做出选择。本文旨在让 Agent 在编写或审查代码时运用这些判断。每条规则都针对一种常见的错误默认做法；对于模型已经能正确处理的内容（语法、基本惯用法、标准库），这里不作规定。

何时应用

• 编写或审查 OTP 代码——判断某项工作是否需要进程，以及该选择哪种进程（GenServer、Task、Agent、ETS、supervisor）
• 处理失败——在带标签的元组、异常、with 和让进程崩溃之间做出选择
• 编写 Ecto——查询、关联、事务、变更集、大型结果集
• 构建 Phoenix 控制器和 LiveView——上下文边界、socket 状态、mount 生命周期
• 运行并发工作——并行扇出、即发即弃任务、处理不可信输入
• 任何要求让 Elixir 代码更符合惯用写法、更能容错或达到“资深工程师级”的请求

规则类别

#	类别	前缀	涵盖内容
1	进程与 OTP 设计	otp-	问题是否需要进程，以及该选择哪种进程；监督
2	错误处理与任其崩溃	err-	如何传达失败；何时引发、捕获或崩溃
3	惯用法与设计选择	data-	模式匹配、Stream/Enum、iolists、管道、宏
4	并发与调度器	conc-	有界且隔离的并行处理；原子表安全
5	Ecto 与数据访问	ecto-	N+1、原子写入、约束竞争、大型数据集
6	Phoenix 与 LiveView	phx-	上下文边界、socket 内存、mount 生命周期

快速参考

1. 进程与 OTP 设计

• otp-genserver-not-default — GenServer 是串行化点，不是默认抽象
• otp-ets-for-shared-reads — 读操作频繁的共享状态应放在 ETS 中，而不是置于 GenServer.get 之后
• otp-supervise-over-manual-restart — 使用子进程规范 + DynamicSupervisor/Registry，而非手写重启逻辑
• otp-handle-continue-init — 将繁重的启动工作延后到 handle_continue；init/1 会阻塞 supervisor

2. 错误处理与任其崩溃

• err-tagged-tuples-vs-raise — 预期中的失败使用 {:ok/:error}，只有违反不变量时才引发异常
• err-let-it-crash — 不要通过捕获异常来掩盖错误；让 supervisor 重启并恢复干净状态
• err-with-happy-path — 使用 with 串联可能失败的步骤；保留原始错误项

3. 惯用法与设计选择

• data-pattern-match-over-conditionals — 根据参数形态使用函数子句 + 守卫，而非 if/cond
• data-stream-vs-enum — 大型、惰性或需要提前退出的处理使用 Stream；小型、具体的列表使用 Enum
• data-iolists-over-concat — 将大型输出构建为 iolists；在循环中使用 <> 的复杂度为 O(n²)
• data-pipe-idioms — 通过转换传递数据主体，而不是为了省略变量而使用管道
• data-functions-over-macros — 优先用函数解决问题，再考虑使用宏

4. 并发与调度器

• conc-async-stream-bounded — 使用带有 max_concurrency 和显式 timeout 的 Task.async_stream
• conc-task-supervised-nolink — 对即发即弃的工作使用受监督、未链接的 Task
• conc-atom-exhaustion — 切勿根据外部输入构建原子；使用 to_existing_atom

5. Ecto 与数据访问

• ecto-preload-n-plus-one — 预加载应提前完成，切勿在 Enum 循环中执行
• ecto-multi-for-transactions — 使用 Ecto.Multi 执行原子多步骤写入，并标明失败原因
• ecto-db-constraints-over-validation — 使用数据库约束和 unique_constraint，不要使用存在竞态条件的验证查询
• ecto-stream-large-sets — 使用 Repo.stream/批处理大型数据集；数据规模增大时，Repo.all 会导致内存溢出
• ecto-atomic-counters — 使用带有 inc: 的 update_all 更新计数器；读取后再写入会导致更新丢失

6. Phoenix 与 LiveView

• phx-context-boundary — Web 层调用上下文，不要直接调用 Repo 或访问架构
• phx-liveview-streams — 对大型或不断增长的集合使用流，不要在 assigns 中存放完整列表
• phx-mount-twice-connected — 使用 connected?/1 控制副作用；mount 会运行两次

使用方法

遇到相关决策时，阅读对应的参考文件。每条规则都会指出它要纠正的错误默认做法，然后展示规范做法（仅在错误做法确实容易造成问题时，才对比错误与正确做法）。

• 章节定义 — 类别结构与排序
• 规则模板 — 用于添加新规则
• AGENTS.md — 自动生成的所有规则目录

参考文件

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与来源引用