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