English | 简体中文

公开 API、错误与文档

公开契约首先面向 C++ 设计。对 Blueprint 有实际用途的操作，通过清晰的适配层或反射入口按需暴露。目前尚未承诺兼容性，但 API 变更仍须在 PR 中明确展示并解释。

契约与所有权

稳定的公开接口使用 UE 类型。非反射的玩法扩展契约使用 C++ 接口；玩法作者需要时提供面向 Blueprint 的适配层。
必须说明每项服务由谁创建、持有和销毁。模块或 Subsystem 管理服务生命周期。纯 C++ 对象所有权可按需使用 TUniquePtr 或 TSharedPtr；原始指针不表示所有权。反射对象遵守 UObject 所有权和垃圾回收规则。
公开方法必须说明可从哪个线程调用，以及回调在哪个线程运行。异步公开回调默认在 Game Thread 执行。
不得在可能超过 UObject 生命周期的任务中捕获没有保护的 UObject 原始指针。应使用合适的弱引用或其他生命周期安全机制。

异步操作与错误

异步公开操作返回取消句柄，并可分别接受成功、取消、超时和失败回调。调用者无需提供所有回调。每个操作恰好执行一个与终态对应的回调；未提供的回调不会被调用。不提供通用的完成回调。
在下游支持取消时，取消操作必须传播到下游。若任务已经完成或无法停止，契约必须说明此时“取消”的含义。
使用包含领域专用错误枚举的统一结果模型。需要更复杂的分类时可加入 Gameplay Tag，仅在必要时补充文本细节。基本错误码不得用任意字符串代替。
check 和 ensure 用于程序员错误或内部不变量。认证失败、无效外部配置、网络故障和玩家输入属于普通结果错误。

必需的 API 文档

对于暴露玩法操作的类，第一个 public: 区域紧跟类开头及 Unreal 反射宏，放置玩法层调用的方法。第二个 public: 区域放置仅供框架集成或 Unreal 生命周期调用的方法。两个 public: 区域之间不得出现其他访问说明符。第二段只表示 C++ 可访问性，不属于玩法 API；其中的方法不要求 Doxygen 注释。不需要外部访问的方法仍应放在 private 或 protected。方法位置取决于预期调用方，而不仅取决于当前是否存在调用处。

所有公开类型、第一个 public: 区域中面向玩法的方法、枚举及枚举值、常量、玩法扩展契约，以及向 Blueprint 暴露的入口，都必须有英文 Doxygen 注释。注释应解释用途和用法，并在适用时说明参数与返回值、所有权与生命周期、线程要求，以及失败、超时和取消语义。每个公开头文件必须包含 @file 注释，以便文件级声明进入生成文档。第二个 public: 区域可按需使用普通实现注释。

声明的覆盖范围、格式、内容与注释单行长度见 Doxygen 注释规范。

PR 检查会要求第一个 public: 区域中的方法具有 Doxygen 注释，并生成 Doxygen HTML；文档错误或警告会导致失败。仓库检查脚本负责区分两段 public:，Doxygen 自动隐藏没有注释的成员。审查者仍需确认玩法注释准确解释行为。合并后，已通过检查的文档会发布到 GitHub Pages。