161 lines
6.3 KiB
Markdown
161 lines
6.3 KiB
Markdown
# Fishing2Server 协作说明
|
||
|
||
## 项目概览
|
||
|
||
这是一个基于 Fantasy.Net 的游戏服务器项目，主要包含四个工程：
|
||
|
||
- `Main`：程序入口、启动流程、日志初始化、运行时配置加载。
|
||
- `Entity`：实体定义、组件定义、共享模型、生成代码、稳定契约。
|
||
- `Hotfix`：业务逻辑、消息处理、HTTP API、辅助类、工厂类、System 扩展，以及可发布/可热更新的逻辑层。
|
||
- `ThirdParty`：本地第三方依赖代码。
|
||
|
||
以当前源码为准，不以旧文档为准。当前 `.csproj` 实际目标框架是 `net10.0`。
|
||
|
||
## 最重要的架构规则
|
||
|
||
这个仓库最核心的规则是：
|
||
|
||
- `Entity` 负责定义。
|
||
- `Hotfix` 负责实际业务逻辑。
|
||
- 业务逻辑优先写成 `Hotfix` 中的静态扩展、`System`、`Helper`、`Factory`、`Handler`、工具类。
|
||
- `Entity` 尽量保持稳定，因为 `Hotfix` 才是后续发布、替换、热更新的主要承载层。
|
||
|
||
具体落地时：
|
||
|
||
- 新增或修改字段、组件、枚举、共享数据结构、协议承载类型，优先放在 `Entity`。
|
||
- 新增或修改玩法流程、消息处理、校验、奖励结算、状态流转、跨模块编排，优先放在 `Hotfix`。
|
||
- 不要把复杂业务直接塞进实体类实例方法里，除非有非常明确的理由，并且符合现有 Fantasy 项目模式。
|
||
|
||
## 目录职责
|
||
|
||
- `Main/Program.cs`：服务启动入口。
|
||
- `Main/NLog.config`：日志配置。
|
||
- `Main/configs.json`：配置相关源定义。
|
||
- `Main/cfg/`：运行时配置表 JSON。
|
||
- `Entity/Authentication`、`Entity/Game`、`Entity/Gate`、`Entity/Model`、`Entity/Modules`：实体和共享模型定义。
|
||
- `Entity/Generate/NetworkProtocol`：协议生成代码。
|
||
- `Entity/Generate/ConfigTable`：配置表生成代码。
|
||
- `Hotfix/Authentication`、`Hotfix/Game`、`Hotfix/Gate`、`Hotfix/Common`、`Hotfix/Api`：业务逻辑实现，其中 HTTP API 相关逻辑统一放在 `Hotfix/Api`。
|
||
- `Tools/NetworkProtocol`：协议定义源文件。
|
||
- `Tools/ProtocolExportTool`：协议导出工具。
|
||
|
||
## 修改代码时的基本判断
|
||
|
||
处理需求时，先判断它属于哪一类：
|
||
|
||
- 如果是“数据长什么样、有哪些字段、有哪些共享结构”，改 `Entity`。
|
||
- 如果是“数据怎么流转、怎么校验、怎么处理、怎么响应”，改 `Hotfix`。
|
||
|
||
默认原则：
|
||
|
||
- 业务变更默认落在 `Hotfix`。
|
||
- 目录结构尽量与现有模块保持对称。
|
||
- 如果实体在 `Entity/Game/Player`，对应逻辑通常应放在 `Hotfix/Game/Player`。
|
||
- 优先复用现有模块，不要随意新起一套平行抽象。
|
||
|
||
## 命名和组织约定
|
||
|
||
遵循现有源码习惯：
|
||
|
||
- `*System`：静态扩展逻辑、Fantasy 系统逻辑。
|
||
- `*Helper`：流程编排、模块辅助逻辑。
|
||
- `*Factory`：对象创建、初始化组装逻辑。
|
||
- `*Handler`：消息处理、RPC 处理、HTTP 处理。
|
||
|
||
命名空间尽量沿用项目现有风格，主要是 `NB.*`。
|
||
|
||
## Entity 与 Hotfix 的边界
|
||
|
||
适合放在 `Entity` 的内容：
|
||
|
||
- Entity / Component 类型定义。
|
||
- 持久化字段和共享字段。
|
||
- 枚举、共享模型、基础契约。
|
||
- `Main` 和 `Hotfix` 都要依赖的公共类型。
|
||
- 生成代码产物。
|
||
|
||
适合放在 `Hotfix` 的内容：
|
||
|
||
- `MessageRPC<,>` 等消息处理器。
|
||
- HTTP API 的 `Controller`、API `Handler`、API `Helper`、中间件及相关业务流程。
|
||
- 对实体/组件的静态扩展方法。
|
||
- 玩法规则、条件校验、奖励发放、状态变化。
|
||
- 场景生命周期逻辑。
|
||
- 登录/JWT/网关业务流程。
|
||
- 工厂、帮助类、缓存协作、跨模块调度。
|
||
|
||
尽量避免：
|
||
|
||
- 在 `Entity` 中直接编写大量玩法逻辑。
|
||
- 直接手改 `Entity/Generate` 下的生成文件。
|
||
- 一边改协议源文件，一边又手工改生成后的协议代码。
|
||
|
||
## 生成代码与源文件规则
|
||
|
||
以下内容默认视为“产物”而不是“手工主编辑区”：
|
||
|
||
- 协议源文件：`Tools/NetworkProtocol/**`
|
||
- 协议生成输出：`Entity/Generate/NetworkProtocol/**`
|
||
- 配置表生成输出：`Entity/Generate/ConfigTable/**`
|
||
- 运行时配置 JSON：`Main/cfg/**`
|
||
|
||
推荐流程：
|
||
|
||
1. 先改源定义。
|
||
2. 再执行生成。
|
||
3. 只有在用户明确要求，或生成链路不可用时，才直接改生成产物。
|
||
|
||
## 常见任务处理方式
|
||
|
||
### 新增玩法或业务功能
|
||
|
||
1. 只有在数据结构必须变化时，才修改 `Entity`。
|
||
2. 实际功能实现放到 `Hotfix`。
|
||
3. 请求入口放在对应模块的 `Handler` 目录。
|
||
4. 跨场景或跨模块编排优先写在 `Helper` 或 `System`，不要堆到 `Main`。
|
||
|
||
### 新增或修改 HTTP API
|
||
|
||
1. HTTP API 相关实现统一放在 `Hotfix/Api`。
|
||
2. 控制器放在 `Hotfix/Api/Controllers`。
|
||
3. API 相关服务注册、处理入口、辅助逻辑分别沿用现有 `Handler`、`Helper`、`Middlewares` 目录结构。
|
||
4. API 只是入口层，真正的业务规则仍应复用 `Hotfix` 内已有模块逻辑，不要在 Controller 中堆积大量业务代码。
|
||
|
||
### 新增或修改网络消息
|
||
|
||
1. 修改 `Tools/NetworkProtocol` 下的协议定义。
|
||
2. 生成到 `Entity/Generate/NetworkProtocol`。
|
||
3. 在 `Hotfix` 中补齐对应处理逻辑。
|
||
4. 非必要不要直接维护 Opcode 或生成消息文件。
|
||
|
||
### 新增或修改配置表
|
||
|
||
1. 先修改配置源。
|
||
2. 如有需要，重新生成 `Entity/Generate/ConfigTable`。
|
||
3. 确保 `Main/cfg` 中的运行时 JSON 与生成类型一致。
|
||
|
||
## 构建与验证
|
||
|
||
仓库根目录常用命令：
|
||
|
||
```powershell
|
||
dotnet build Server.sln
|
||
dotnet build Main/Main.csproj
|
||
dotnet build Entity/Entity.csproj
|
||
dotnet build Hotfix/Hotfix.csproj
|
||
dotnet run --project Main/Main.csproj
|
||
```
|
||
|
||
完成较大改动前，建议至少做这些检查：
|
||
|
||
- 优先构建受影响最小的项目。
|
||
- 如果公共契约变了，构建整个解决方案。
|
||
- 如果动了协议或配置生成链路，确认生成代码和 `Hotfix` 使用方都能正常编译。
|
||
|
||
## 额外注意事项
|
||
|
||
- 工作区可能已经有用户自己的未提交改动，不要回滚无关内容。
|
||
- 仓库中已有 `bin/`、`obj/` 等构建产物目录，除非任务明确要求，否则忽略它们。
|
||
- `CODELY.md` 可以作为背景参考，但其中部分信息已经滞后；若与源码冲突，以源码和项目文件为准。
|
||
- 当需求描述不够明确时，优先按本项目既有架构理解：稳定定义放 `Entity`，可变业务放 `Hotfix`。
|