joywayerandClaude Opus 4.8
6b00b80741
链接目标本就是相对路径，但显示文字硬写了 docs/xxx/development-guide 这类绝对式路径名——目录一旦整体移动，文字即过时（链接仍可跳）。 将 10 处显示文字统一改为「篇号 + 篇名」等只依赖文档自身、不依赖 所在路径的写法（如 docs/server/development-guide/03 §6 → 03 §6「端到端收发全链路」），engineering README 自称路径同样收敛为 泛指的 engineering/。至此保持三套目录相对位置不变即无需改任何链接。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
子游戏前后端开发规范 · 工程与架构通则
本套文档总结一套专业、成熟、平台无关的子游戏开发规范。它不讲某个平台怎么接入， 而是从架构与工程的角度，给出前后端通用的设计原则、可扩展模式、配置化实践与反模式清单， 指导开发者写出优雅、现代、易演进、少返工的子游戏代码。
这套文档解决什么
平台接入细节（三层路由、export/import、收发包协议、ES5/require 等）已在各端
development-guide/ 中讲清；本套文档是它们之上的工程方法论：
- 怎样分层，让依赖单向、边界清晰、改一处不牵一身；
- 怎样扩展，让新增玩法/规则/策略是"加代码"而非"改核心"；
- 怎样配置化，把会变的东西从硬编码里拿出来，用数据驱动；
- 怎样守住数据权威，让同一份数据只有一个来源、缺失即显式失败；
- 怎样不过度设计，在"能扩展"与"够简单"之间拿捏。
一句话定位：平台接入是"能不能跑通"，本套规范是"跑得久、改得动、错得少"。
阅读导航
| 篇 | 文档 | 解决什么 |
|---|---|---|
| 00 | 本文 README | 定位、适用范围、一页纸总则、与既有文档的关系 |
| 01 | 01-架构总则与分层.md | 七大架构总则；前后端参考分层；依赖方向与稳定依赖 |
| 02 | 02-可扩展性与配置化.md | 扩展模式（注册表/策略/管线/工厂/事件）何时用；配置化与去硬编码；避免过度设计 |
| 03 | 03-数据权威·错误处理·演进.md | 数据权威（前后端）；错误处理与可观测；演进与重构；反模式与审查清单 |
一页纸：七大总则
- 单一权威数据源（SSOT）：同一业务数据只有一个计算/写入处，其他只读；缺失即显式失败，不兜底掩盖。
- 单向依赖：分层自上而下依赖，稳定的被依赖、易变的作依赖方；禁止环形依赖。
- 职责单一、边界清晰：一个职能只在一个模块实现，别处调用而非重造。
- 关注点分离：决策与机制分离、数据与表现分离、编排与算法分离。
- 对扩展开放、对修改封闭（OCP）：用注册/策略/管线加能力，不改动已稳定的核心。
- 配置优先于硬编码：会变、复用、无语义的值一律外提为常量/配置，用数据驱动行为。
- 显式失败优于隐式兜底：关键路径缺数据就报错/返回
null，把问题暴露在最近处。
这七条互相支撑：SSOT + 显式失败保正确，单向依赖 + 职责单一 + 关注点分离保清晰， OCP + 配置化保可演进。任何设计取舍，回到这七条对照。
适用范围与边界
- 适用：子游戏自身的前后端业务代码（玩法逻辑、对局编排、收发包处理、表现层、共享算法）。
- 不覆盖：平台框架代码（不可改）、平台接入契约（见各端
development-guide/）。 - 与硬约束的关系：ES5、
require守卫、可编辑范围、成败标志data.success等硬红线仍以development-guide/为准；本套是方法论层，与之互补不冲突。
与既有文档的关系
| 文档 | 定位 |
|---|---|
各端 development-guide/ |
平台接入 + 工程红线（能跑、合规） |
本套 engineering/ |
平台无关的通用工程与架构规范（该怎么设计） |
具体命名（模块名/文件名/方法名）在本套文档里多为示例、可自定；约束的是做法与结构，不是具体名字。