SpacetimeDB 文档写作风格指南从术语规范到参考页、教程页的完整实践手册【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB导读本文档系统梳理 SpacetimeDB 开源仓库中 docs/STYLE.md 所确立的官方文档写作规范涵盖目标读者定位、代码与元变量格式、核心术语表、参考页Reference与教程页Tutorial的章节结构与语气要求并结合仓库内真实的文档组织方式如 docs/docs 目录下的核心概念、资源参考与 BSATN 内部文档给出源码级佐证。读完本文你将掌握一套可直接复用的技术文档写作纪律既能写出面向 Web/游戏开发者、避免形式化符号堆砌的入门材料也能写出符合百科全书式语气的 API 参考页以及可整体复制粘贴成可运行程序的分步教程。一、为什么需要一份文档风格指南SpacetimeDB 的仓库规模横跨 Rust、C#、TypeScript、C 等多个语言生态其文档最终会呈现在 SpacetimeDB 官网上并被大量开发者、搜索引擎、Agent 与 LLM 检索引用。文档风格指南存在的意义不是束缚写作者的个性而是保证以下几点一致性同一概念在不同页面使用同一术语例如模块与数据库的严格区分可检索性稳定的标题结构、代码语言标记、锚点链接让读者和自动化工具都能快速定位诚实性明确区分已实现的功能与尚未实现的内容避免误导用户。该指南在仓库中的定位见 docs/STYLE.md 开头它承认仓库现有文档目前并未全部达到这些标准但要求新增文本必须达标对不符合规范的文档 PR 将要求修改或直接拒绝——即使这些 PR 是在改写同样不合规的旧文档。这是一份面向未来的写作纪律而不是对历史遗留的追认。二、通用写作准则General Guidelines2.1 目标读者懂业务、未必懂形式化理论SpacetimeDB 文档的默认读者是胜任的 Web 或游戏开发者但不一定有深厚的理论数学或计算机科学功底。因此文档应尽量避免过于简练的形式化符号改用自然语言解释原理。例如与其写一堆类型论记号不如直接用英文句子说明这行代码做了什么。例外内部文档Internals Docs。对底层、低阶或高级接口的文档如 BSATN 二进制编码、模块 ABI可以假定读者有更强的技术背景。但这类页面必须在开头明确声明SUBJECT 是 HIGHER-LEVEL SYSTEM 的底层实现细节。HIGHER-LEVEL SYSTEM 的使用者无需关心 SUBJECT。本文面向高级用户和好奇 SpacetimeDB 内部机制的读者。 同时要把 HIGHER-LEVEL SYSTEM 链接到面向用户的组件文档。仓库中的实证内部文档 BSATN Data Format 就是这类给少数人看的页面它直接采用归纳定义与bsatn(x)函数记法并明确给出代数值、和值SumValue、积值ProductValue的字节级编码规则——这些内容不会出现在普通入门教程中。2.2 代码格式代码块与行内代码的边界任何超过100 字符宽终端上的一行的一半长度的示例都必须使用三反引号代码块并始终给出语言标记用于语法高亮。仓库推荐的高亮语言为csharp、rust、typescript、sql。变量、函数、方法等符号名使用单反引号行内代码尽可能做成指向文档中对应章节的锚点链接。正文中需要用户自行填充的**元变量meta-variable**用斜体表示不加反引号并必须附上说明其含义的句子或 where 子句。代码块中的元变量用{}花括号包裹且与正文中使用的元变量名称保持一致。以原文档给出的标准示例为例该示例描述的是在唯一列上查找行可直接对照仓库 Rust SDK 中find方法的实际用法见 client_cache.rs要在表table的#[unique]或#[primary_key]列上按给定值查找行可以这样写ctx.db.{table}().{column}().find({value})其中column是唯一列的名称value是你想在该列中查找的值。例如ctx.db.people().name().find(Billy)这等价于SELECT * FROM {table} WHERE {column} {value}关键纪律不要用单反引号给非符号名的词加代码高亮不能拿代码高亮当强调或用于引入新词汇不要用斜体修饰非元变量的词。元语法本身不是合法语法所以后面必须跟一个落地的具体示例。2.3 伪代码能写真代码就别写伪代码尽量直接使用受支持语言的真实代码而不是伪代码。如果文档文件本身针对某一特定语言就用该语言如果面向整个系统则尽量用你擅长的多种受支持语言各写一份再请团队里懂其他语言的同事补齐。如果某段代码仅为教学目的、包含虚构函数只要函数名有描述性即可但必须在代码块前注明此代码不能按原样运行。2.4 描述限制与未来计划诚实优于承诺未实现的功能称为当前限制current limitationsBug 称为已知问题known issues要坦率地说明目前哪些功能还没实现宁可提前告知用户这个还坏着/还没做完也不要让用户期待落空不要在教程或参考文档中做任何未来承诺哪怕是很弱的承诺。关于未来的表述应放到独立的 roadmap 或 future plans 文档中如果文档必须涉及未实现的功能要么重写以不依赖该功能要么直接标注为当前限制并附上可行的变通方案workaround。2.5 菜单项与路径加粗 箭头分隔描述 GUI 元素如Unity Registry标签页时用加粗标出会真实出现在界面上的词并附一句简短的元素类别说明如标签页类别本身不加粗。描述菜单层级访问链时用-连字符大于号作分隔符整条序列加粗自顶层菜单从左到右列全File - Quit、Window - Package Manager、Foo - Bar - Baz - Quux。不要画蛇添足地写左上角的File菜单——菜单位置会随操作系统、版本、桌面环境、主题而变化除非你有绝对把握否则信任读者熟悉自己使用的软件。2.6 表名规范一律单数表名使用单数形式user而非users、player而非players。这同时适用于 SQL 代码片段和模块代码。在模块代码中表名还要遵守该语言的方法命名惯例Rust 用snake_caseC# 用PascalCase。例如每名玩家一行、记录最近登录时间的表在 Rust 模块中叫player_last_login_time在 C# 模块中叫PlayerLastLoginTime。这一规范在仓库的模块代码与文档中随处可见例如 reducers 文档 中的user表定义以及 templates/basic-rs 等模板项目里的单数表名。三、关键词汇表必须一致的术语体系风格指南强调有少量关键术语需要在整个文档中保持一致其中最重要的区分如下数据库Database运行在主机上的活跃实体包含一系列表像普通数据库一样并具备额外能力——客户端可直接连接它并远程调用其存储过程。模块Module开发者用来定义数据库的源代码是数据库 schema 一组存储过程的组合。构建并发布后模块成为运行中数据库的一部分。关系是数据库拥有模块模块是数据库的一部分。模块本身不运行在主机上——是数据库运行在主机上。客户端不连接模块而是连接数据库。风格指南特别强调正在运行的应用程序绝不称为模块Module只是指代存储过程集合的一个怪癖词汇。其余核心术语的完整清单如下术语含义SpacetimeDB主机 Host托管数据库的应用程序多租户可同时托管多个数据库客户端 Client任何连接到数据库的应用程序终端用户 End user任何使用客户端的用户数据库开发者 Database developer维护数据库的人文档中不要称其为 users内部口头称呼可以公开文档请用database developers表 Table一组带类型、带标签的行用于在数据库中存储数据列 Column / 行 Row行存储若干列的数据不要把行称为tuple因为这与模块语言中的tuple 类型混淆tuple只用于指代这类类型的元素归约器 Reducer可被远程调用以更新数据库的存储过程它其实并不reduce数据但改名已晚Cest la vie连接 Connection客户端与数据库之间的连接会获得一个地址Address单个连接可打开多个订阅订阅 Subscription将数据库数据镜像到客户端的活动查询地址 Address活动连接的标识符身份 Identity一个 OpenID Connect 颁发者与其签发的 Identity Token 的组合全局唯一且公开技术上应叫 Identifier 但改名已晚一个终端用户可能有多个不同颁发者签发的身份每个数据库也有一个身份这套术语可以直接对照仓库中的实际概念实现订阅查询与一次性查询的区别见 订阅语义文档身份/鉴权体系见 Authentication 章节reducer 的完整定义与生命周期见 Reducers 文档。四、参考页Reference Pages写作规范参考页是中级用户浏览工具全部能力的入口也是经验丰富的用户核对类型、函数、方法行为细节的地方。SpacetimeDB 生态中每个面向用户的组件都应该有一个参考页。参考页必须以一段引言开头说明该组件是什么、用户何时以及如何与之交互然后要么包含安装/设置章节要么链接到完成同样目的的页面。4.1 语气、时态与语态参考页应使用相对正式的语言风格接近百科全书或教科书风格指南原文明示可对标 .NET API 参考文档。具体规则陈述式现在时描述属性/函数/方法的行为。例如本类型的所有公共静态成员都是线程安全的任何实例成员都不保证线程安全。通常不要提及读者少用第二人称 you只在需要提示读者规避坑时使用且应把这类提醒抽到 note、warning 或引用块中。通常不要提我们/我少用第一人称仅在传达设计建议这类非技术信息时使用且永远用第一人称复数 we/us绝不用单数 I/me常配 recommendadviseencouragediscourage 等标记词。通常避免被动语态主动语态能直接归因动作主体消除歧义。例如被动句 The method was invoked. 应改为主动向 The user invoked the method.。但当动作主体未知或无关时被动语态是恰当的如 TheDisposemethod is called automatically when the object is garbage collected.4.2 表格与链接每个参考页应有一个或多个两列表格左列是带命名空间限定的名称或签名用代码格式并链接到对应定义页/段落右列是一句话描述。表头可选若表格包含多种条目如类型与函数左列应以后缀标明种类。鼓励一页内用标题分隔多个表格例如按类与接口分组。4.3 单个定义的小节格式为某个定义变量/函数/方法撰写小节时遵循固定的层次结构Header先给出元数据如命名空间再用一句陈述式现在时、主动动词开头的话概括该对象被定义对象为隐含主语例如 Implements the IList interface using an array whose size is dynamically increased as required.声明/签名代码块放一个仅含声明或签名的三反引号代码块。什么算声明视上下文而定——一个通用规则是源码中位于等号或花括号{}左侧的全部内容。可以删去实现细节如用户不该看到的父类也可以补充源码中没有但有用的信息如HashMap泛型参数上方法通常要求的Eq Hashtrait 约束。深入描述必要时补充一段或多段更详细的说明。Examples 子标题放入示例代码块。示例应尽量独立成篇若依赖非标准库的外部定义要加注说明例如mod module_bindings;指的是quickstart-chat模块。给代码加注释说明行为若示例会打印输出用注释展示预期输出。不要害怕把同一段头/prelude代码如表声明复制进多个代码块但要避免对这些头代码做不易察觉的小改动。子条目Child items若被描述对象有子成员类的属性/方法、枚举的变体按上述方式列出表格并为每个子条目追加同格式的小节。当嵌套层级超过 3 层时拆分页面让每个顶层条目独占一页。4.4 文法与语法Grammars and Syntax参考文档尤其是 SQL 或序列化格式相关有时需要描述文法。风格指南先给了一个劝告先确认你真的需要因为文法规范对中等技术水平的读者来说是吓人的。如果描述的数据遵循读者熟悉的另一种语言直接用那种语言写定义例如描述 JSON 编码时考虑用 TypeScript 风格的类型而非文法确需描述文法时在三反引号代码块中写 EBNF语言标记为ebnf。从最顶层/入口非终结符开始向下推进到终结符如描述 SQL 时statement在顶层literal和ident在底部或接近底部琐碎规则如 literal可以省略然后在 Examples 子标题下的另一个代码块中给出一大堆示例语言标记与所描述内容匹配至少包含一个简单示例和一个复杂示例并尽量覆盖文法能表达的所有特性。仓库实证BSATN 内部文档 00300-bsatn.md 正是这种必要之处用形式化记法、并辅以逐条展开的写法——它先用归纳记法定义bsatn(x)再给出SumValue、ProductValue、ArrayValue、字符串与全部基本类型的字节级编码公式。五、概览页Overview Pages写作规范概览页是着陆页性质的内容通常命名为index.md仓库中如 Core Concepts 索引 即为此类。语气沿用参考页的规范但可以更频繁地用 you 称呼读者链接在正文中尽可能多地链接到更具体的文档页指向其他页面内锚点的 sharp 链接尤其有价值如上文提到的 00000-index.md 就对数据库、表、函数、鉴权、客户端等每个章节都给出了链接FAQ有些想传达给用户却塞不进其他页面/章节的信息就放到概览页底部的 FAQ 章节。每个 FAQ 条目以子标题开头且措辞为用户会问的问题答案以陈述句或对话句开头用 you 称呼提问者用 your clientyour moduleyour app 指代其项目。FAQ 写法示例取自原文档订阅查询和一次性查询有什么区别订阅查询是增量的数据库状态变化时你的客户端会收到更新且只包含被改动的行。这是维护物化视图即数据库某个子集的本地副本的高效方式。当你想要观察行并对其变化做出反应或想保留会频繁读取的行的本地副本时用订阅。一次性查询只执行一次就结束了。当你只需要看一次某些行时用它。我的客户端能同时连接多个数据库吗能你的客户端想同时构造多少个DbConnection都可以彼此独立运行。如果要连接两个 schema 不同的数据库用spacetime generate把两者的绑定都包含进客户端项目。注意 SpacetimeDB 可能会拒绝单个客户端对同一数据库的多个并发连接。六、教程页Tutorial Pages写作规范教程用于把新到中级用户引入新概念。与特定组件相关的教程应放在该组件文档旁子目录中更综合、覆盖 SpacetimeDB 多个部分以产出完整游戏/应用的教程应独立成篇或归入 tutorials/projects 目录。6.1 语气与范围语气友好但依然精确专业用 you 称呼读者可选的动作用 can/could 温和建议推进教程所必需的动作用祈使句回顾过去教程或为后续铺垫时说 we把写作者与读者绑在一起。范围不必教读者非 SpacetimeDB 特有的知识。例如写 Rust 模块教程时假定读者有基础到中等的 Rust 水平把教学重点放在 modules 部分。6.2 开头先告诉他们你将讲什么每个教程开头都要声明三件事范围scope会引入哪些新概念目标goal教程过程中你会构建或完成什么前置条件prerequisites应该先完成哪些其他教程。原文档示例在本教程中我们将实现一个简单的聊天服务器作为 SpacetimeDB 模块。我们将学习如何声明表、编写 reducer——即在数据库中运行、响应客户端请求来修改这些表的函数。开始之前请确保你已安装 SpacetimeDB 并登录开发者身份。6.3 定义引入与教程代码系列中首次引入新类型/函数/方法时写一小段说明它是什么、在本教程中如何被使用并链接到该条目的参考章节教程涉及写代码时必须在正文中给出完整的最终结果代码。理想情况下读者把文中所有代码块复制拼接起来就能得到一个连贯可运行的程序。若不可能如 C# 需要把整个文件包进一系列作用域就在每个代码块前用一句话说明读者应将其粘贴到哪里连 imports 这类无趣代码也要包含。可以快速带过但要保证让项目跑起来所需的每一行代码都出现在教程里对有趣的代码代码块后要描述它做了什么通常保持简洁提示用户写代码时不要说 copy 或 paste而是用祈使句 add 或 write——这强调主动参与而非被动照抄也隐式鼓励读者按需修改示例代码。6.4 结尾Whats next每个教程都应以类似 Whats next? 的标题结尾包含两部分回顾Tell em what you told em用一两句话提醒读者他们完成了什么如 你刚刚在 SpacetimeDB 中搭起了第一个数据库连同它专属的表和 reducer指引下一步Tell them what to do next若教程属于系列链接下一篇若教程针对特定组件链接其参考页若教程是系列终点或产出完整应用抛出一些读者可以自行扩展的方向如改进终端界面、限制消息订阅范围、给用户表加moderator标志、添加房间/频道、支持私信等完整代码链接教程若涉及写代码应链接到完整代码所在位置自有仓库或现有仓库中的示例项目并确保该目录含 README.md其中包含教程项目名称、如何运行/交互如发布到 maincloud 后用spacetime call、外部依赖链接如客户端项目所依赖的模块、指向构建该项目的教程的反向链接。仓库实证本仓库中的完整模板项目如 templates/chat-console-rs、templates/basic-rs、demo/Blackholio即是教程产出完整可运行代码这一原则的载体而spacetime init预生成的模块骨架见 spacetime dev 指南正是原文档示例中清空server/src/lib.rs里的 trivial 模块写入我们自己的聊天服务器的前提。七、风格规范在仓库中的落地与自检清单这份风格指南并非纸上谈兵仓库中已有多个机制将规范落到实处文档结构即规范docs 站点的内容被组织为 核心概念、资源参考 等区块概览页链接到具体页面、参考页与教程页分层存放与概览页密集链接、参考页分条定义、教程页可拼接运行的三类规范一一对应。LLM 基准工具直接消费文档docs/DEVELOP.md 记录了 LLM 基准测试如何把文档作为上下文喂给模型——它按语言过滤Tabs组件只保留目标语言标签页的内容。这反过来对文档写作提出硬性要求必须使用一致的 tab groupId服务端模块代码用server-language客户端 SDK 代码用client-language、必须为所有受支持语言提供 tab、命名约定要与 golden answer 一致如 C# 表名用 PascalCase。这正是风格指南中表名单数/大小写规范的价值所在——不一致的文档会让自动化评测和读者双双踩坑。内部文档的贴标签实践BSATN、模块 ABI 等页面明确以内部/低级接口定位示人遵循了为高级读者准备、并对更高层系统给出链接的例外条款。给写作者的最终自检清单术语是否与第三节词汇表一致模块 vs 数据库、订阅 vs 一次性查询、Identity vs 用户表名是否单数、是否符合语言的大小写惯例代码块是否都带语言标记元变量是否用{}包裹并附说明参考页是否用陈述式现在时、主动语态是否包含两列表格与签名代码块教程是否声明了范围/目标/前置条件代码能否复制拼接后运行结尾是否有 Whats next?是否坦率标注了当前限制/已知问题而没有对未来的空头承诺把这套纪律内化你就写出了能被人类愉快阅读、也能被搜索引擎与 LLM 准确理解的 SpacetimeDB 文档。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SpacetimeDB 文档写作风格指南：从术语规范到参考页、教程页的完整实践手册
SpacetimeDB 文档写作风格指南从术语规范到参考页、教程页的完整实践手册【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB导读本文档系统梳理 SpacetimeDB 开源仓库中 docs/STYLE.md 所确立的官方文档写作规范涵盖目标读者定位、代码与元变量格式、核心术语表、参考页Reference与教程页Tutorial的章节结构与语气要求并结合仓库内真实的文档组织方式如 docs/docs 目录下的核心概念、资源参考与 BSATN 内部文档给出源码级佐证。读完本文你将掌握一套可直接复用的技术文档写作纪律既能写出面向 Web/游戏开发者、避免形式化符号堆砌的入门材料也能写出符合百科全书式语气的 API 参考页以及可整体复制粘贴成可运行程序的分步教程。一、为什么需要一份文档风格指南SpacetimeDB 的仓库规模横跨 Rust、C#、TypeScript、C 等多个语言生态其文档最终会呈现在 SpacetimeDB 官网上并被大量开发者、搜索引擎、Agent 与 LLM 检索引用。文档风格指南存在的意义不是束缚写作者的个性而是保证以下几点一致性同一概念在不同页面使用同一术语例如模块与数据库的严格区分可检索性稳定的标题结构、代码语言标记、锚点链接让读者和自动化工具都能快速定位诚实性明确区分已实现的功能与尚未实现的内容避免误导用户。该指南在仓库中的定位见 docs/STYLE.md 开头它承认仓库现有文档目前并未全部达到这些标准但要求新增文本必须达标对不符合规范的文档 PR 将要求修改或直接拒绝——即使这些 PR 是在改写同样不合规的旧文档。这是一份面向未来的写作纪律而不是对历史遗留的追认。二、通用写作准则General Guidelines2.1 目标读者懂业务、未必懂形式化理论SpacetimeDB 文档的默认读者是胜任的 Web 或游戏开发者但不一定有深厚的理论数学或计算机科学功底。因此文档应尽量避免过于简练的形式化符号改用自然语言解释原理。例如与其写一堆类型论记号不如直接用英文句子说明这行代码做了什么。例外内部文档Internals Docs。对底层、低阶或高级接口的文档如 BSATN 二进制编码、模块 ABI可以假定读者有更强的技术背景。但这类页面必须在开头明确声明SUBJECT 是 HIGHER-LEVEL SYSTEM 的底层实现细节。HIGHER-LEVEL SYSTEM 的使用者无需关心 SUBJECT。本文面向高级用户和好奇 SpacetimeDB 内部机制的读者。 同时要把 HIGHER-LEVEL SYSTEM 链接到面向用户的组件文档。仓库中的实证内部文档 BSATN Data Format 就是这类给少数人看的页面它直接采用归纳定义与bsatn(x)函数记法并明确给出代数值、和值SumValue、积值ProductValue的字节级编码规则——这些内容不会出现在普通入门教程中。2.2 代码格式代码块与行内代码的边界任何超过100 字符宽终端上的一行的一半长度的示例都必须使用三反引号代码块并始终给出语言标记用于语法高亮。仓库推荐的高亮语言为csharp、rust、typescript、sql。变量、函数、方法等符号名使用单反引号行内代码尽可能做成指向文档中对应章节的锚点链接。正文中需要用户自行填充的**元变量meta-variable**用斜体表示不加反引号并必须附上说明其含义的句子或 where 子句。代码块中的元变量用{}花括号包裹且与正文中使用的元变量名称保持一致。以原文档给出的标准示例为例该示例描述的是在唯一列上查找行可直接对照仓库 Rust SDK 中find方法的实际用法见 client_cache.rs要在表table的#[unique]或#[primary_key]列上按给定值查找行可以这样写ctx.db.{table}().{column}().find({value})其中column是唯一列的名称value是你想在该列中查找的值。例如ctx.db.people().name().find(Billy)这等价于SELECT * FROM {table} WHERE {column} {value}关键纪律不要用单反引号给非符号名的词加代码高亮不能拿代码高亮当强调或用于引入新词汇不要用斜体修饰非元变量的词。元语法本身不是合法语法所以后面必须跟一个落地的具体示例。2.3 伪代码能写真代码就别写伪代码尽量直接使用受支持语言的真实代码而不是伪代码。如果文档文件本身针对某一特定语言就用该语言如果面向整个系统则尽量用你擅长的多种受支持语言各写一份再请团队里懂其他语言的同事补齐。如果某段代码仅为教学目的、包含虚构函数只要函数名有描述性即可但必须在代码块前注明此代码不能按原样运行。2.4 描述限制与未来计划诚实优于承诺未实现的功能称为当前限制current limitationsBug 称为已知问题known issues要坦率地说明目前哪些功能还没实现宁可提前告知用户这个还坏着/还没做完也不要让用户期待落空不要在教程或参考文档中做任何未来承诺哪怕是很弱的承诺。关于未来的表述应放到独立的 roadmap 或 future plans 文档中如果文档必须涉及未实现的功能要么重写以不依赖该功能要么直接标注为当前限制并附上可行的变通方案workaround。2.5 菜单项与路径加粗 箭头分隔描述 GUI 元素如Unity Registry标签页时用加粗标出会真实出现在界面上的词并附一句简短的元素类别说明如标签页类别本身不加粗。描述菜单层级访问链时用-连字符大于号作分隔符整条序列加粗自顶层菜单从左到右列全File - Quit、Window - Package Manager、Foo - Bar - Baz - Quux。不要画蛇添足地写左上角的File菜单——菜单位置会随操作系统、版本、桌面环境、主题而变化除非你有绝对把握否则信任读者熟悉自己使用的软件。2.6 表名规范一律单数表名使用单数形式user而非users、player而非players。这同时适用于 SQL 代码片段和模块代码。在模块代码中表名还要遵守该语言的方法命名惯例Rust 用snake_caseC# 用PascalCase。例如每名玩家一行、记录最近登录时间的表在 Rust 模块中叫player_last_login_time在 C# 模块中叫PlayerLastLoginTime。这一规范在仓库的模块代码与文档中随处可见例如 reducers 文档 中的user表定义以及 templates/basic-rs 等模板项目里的单数表名。三、关键词汇表必须一致的术语体系风格指南强调有少量关键术语需要在整个文档中保持一致其中最重要的区分如下数据库Database运行在主机上的活跃实体包含一系列表像普通数据库一样并具备额外能力——客户端可直接连接它并远程调用其存储过程。模块Module开发者用来定义数据库的源代码是数据库 schema 一组存储过程的组合。构建并发布后模块成为运行中数据库的一部分。关系是数据库拥有模块模块是数据库的一部分。模块本身不运行在主机上——是数据库运行在主机上。客户端不连接模块而是连接数据库。风格指南特别强调正在运行的应用程序绝不称为模块Module只是指代存储过程集合的一个怪癖词汇。其余核心术语的完整清单如下术语含义SpacetimeDB主机 Host托管数据库的应用程序多租户可同时托管多个数据库客户端 Client任何连接到数据库的应用程序终端用户 End user任何使用客户端的用户数据库开发者 Database developer维护数据库的人文档中不要称其为 users内部口头称呼可以公开文档请用database developers表 Table一组带类型、带标签的行用于在数据库中存储数据列 Column / 行 Row行存储若干列的数据不要把行称为tuple因为这与模块语言中的tuple 类型混淆tuple只用于指代这类类型的元素归约器 Reducer可被远程调用以更新数据库的存储过程它其实并不reduce数据但改名已晚Cest la vie连接 Connection客户端与数据库之间的连接会获得一个地址Address单个连接可打开多个订阅订阅 Subscription将数据库数据镜像到客户端的活动查询地址 Address活动连接的标识符身份 Identity一个 OpenID Connect 颁发者与其签发的 Identity Token 的组合全局唯一且公开技术上应叫 Identifier 但改名已晚一个终端用户可能有多个不同颁发者签发的身份每个数据库也有一个身份这套术语可以直接对照仓库中的实际概念实现订阅查询与一次性查询的区别见 订阅语义文档身份/鉴权体系见 Authentication 章节reducer 的完整定义与生命周期见 Reducers 文档。四、参考页Reference Pages写作规范参考页是中级用户浏览工具全部能力的入口也是经验丰富的用户核对类型、函数、方法行为细节的地方。SpacetimeDB 生态中每个面向用户的组件都应该有一个参考页。参考页必须以一段引言开头说明该组件是什么、用户何时以及如何与之交互然后要么包含安装/设置章节要么链接到完成同样目的的页面。4.1 语气、时态与语态参考页应使用相对正式的语言风格接近百科全书或教科书风格指南原文明示可对标 .NET API 参考文档。具体规则陈述式现在时描述属性/函数/方法的行为。例如本类型的所有公共静态成员都是线程安全的任何实例成员都不保证线程安全。通常不要提及读者少用第二人称 you只在需要提示读者规避坑时使用且应把这类提醒抽到 note、warning 或引用块中。通常不要提我们/我少用第一人称仅在传达设计建议这类非技术信息时使用且永远用第一人称复数 we/us绝不用单数 I/me常配 recommendadviseencouragediscourage 等标记词。通常避免被动语态主动语态能直接归因动作主体消除歧义。例如被动句 The method was invoked. 应改为主动向 The user invoked the method.。但当动作主体未知或无关时被动语态是恰当的如 TheDisposemethod is called automatically when the object is garbage collected.4.2 表格与链接每个参考页应有一个或多个两列表格左列是带命名空间限定的名称或签名用代码格式并链接到对应定义页/段落右列是一句话描述。表头可选若表格包含多种条目如类型与函数左列应以后缀标明种类。鼓励一页内用标题分隔多个表格例如按类与接口分组。4.3 单个定义的小节格式为某个定义变量/函数/方法撰写小节时遵循固定的层次结构Header先给出元数据如命名空间再用一句陈述式现在时、主动动词开头的话概括该对象被定义对象为隐含主语例如 Implements the IList interface using an array whose size is dynamically increased as required.声明/签名代码块放一个仅含声明或签名的三反引号代码块。什么算声明视上下文而定——一个通用规则是源码中位于等号或花括号{}左侧的全部内容。可以删去实现细节如用户不该看到的父类也可以补充源码中没有但有用的信息如HashMap泛型参数上方法通常要求的Eq Hashtrait 约束。深入描述必要时补充一段或多段更详细的说明。Examples 子标题放入示例代码块。示例应尽量独立成篇若依赖非标准库的外部定义要加注说明例如mod module_bindings;指的是quickstart-chat模块。给代码加注释说明行为若示例会打印输出用注释展示预期输出。不要害怕把同一段头/prelude代码如表声明复制进多个代码块但要避免对这些头代码做不易察觉的小改动。子条目Child items若被描述对象有子成员类的属性/方法、枚举的变体按上述方式列出表格并为每个子条目追加同格式的小节。当嵌套层级超过 3 层时拆分页面让每个顶层条目独占一页。4.4 文法与语法Grammars and Syntax参考文档尤其是 SQL 或序列化格式相关有时需要描述文法。风格指南先给了一个劝告先确认你真的需要因为文法规范对中等技术水平的读者来说是吓人的。如果描述的数据遵循读者熟悉的另一种语言直接用那种语言写定义例如描述 JSON 编码时考虑用 TypeScript 风格的类型而非文法确需描述文法时在三反引号代码块中写 EBNF语言标记为ebnf。从最顶层/入口非终结符开始向下推进到终结符如描述 SQL 时statement在顶层literal和ident在底部或接近底部琐碎规则如 literal可以省略然后在 Examples 子标题下的另一个代码块中给出一大堆示例语言标记与所描述内容匹配至少包含一个简单示例和一个复杂示例并尽量覆盖文法能表达的所有特性。仓库实证BSATN 内部文档 00300-bsatn.md 正是这种必要之处用形式化记法、并辅以逐条展开的写法——它先用归纳记法定义bsatn(x)再给出SumValue、ProductValue、ArrayValue、字符串与全部基本类型的字节级编码公式。五、概览页Overview Pages写作规范概览页是着陆页性质的内容通常命名为index.md仓库中如 Core Concepts 索引 即为此类。语气沿用参考页的规范但可以更频繁地用 you 称呼读者链接在正文中尽可能多地链接到更具体的文档页指向其他页面内锚点的 sharp 链接尤其有价值如上文提到的 00000-index.md 就对数据库、表、函数、鉴权、客户端等每个章节都给出了链接FAQ有些想传达给用户却塞不进其他页面/章节的信息就放到概览页底部的 FAQ 章节。每个 FAQ 条目以子标题开头且措辞为用户会问的问题答案以陈述句或对话句开头用 you 称呼提问者用 your clientyour moduleyour app 指代其项目。FAQ 写法示例取自原文档订阅查询和一次性查询有什么区别订阅查询是增量的数据库状态变化时你的客户端会收到更新且只包含被改动的行。这是维护物化视图即数据库某个子集的本地副本的高效方式。当你想要观察行并对其变化做出反应或想保留会频繁读取的行的本地副本时用订阅。一次性查询只执行一次就结束了。当你只需要看一次某些行时用它。我的客户端能同时连接多个数据库吗能你的客户端想同时构造多少个DbConnection都可以彼此独立运行。如果要连接两个 schema 不同的数据库用spacetime generate把两者的绑定都包含进客户端项目。注意 SpacetimeDB 可能会拒绝单个客户端对同一数据库的多个并发连接。六、教程页Tutorial Pages写作规范教程用于把新到中级用户引入新概念。与特定组件相关的教程应放在该组件文档旁子目录中更综合、覆盖 SpacetimeDB 多个部分以产出完整游戏/应用的教程应独立成篇或归入 tutorials/projects 目录。6.1 语气与范围语气友好但依然精确专业用 you 称呼读者可选的动作用 can/could 温和建议推进教程所必需的动作用祈使句回顾过去教程或为后续铺垫时说 we把写作者与读者绑在一起。范围不必教读者非 SpacetimeDB 特有的知识。例如写 Rust 模块教程时假定读者有基础到中等的 Rust 水平把教学重点放在 modules 部分。6.2 开头先告诉他们你将讲什么每个教程开头都要声明三件事范围scope会引入哪些新概念目标goal教程过程中你会构建或完成什么前置条件prerequisites应该先完成哪些其他教程。原文档示例在本教程中我们将实现一个简单的聊天服务器作为 SpacetimeDB 模块。我们将学习如何声明表、编写 reducer——即在数据库中运行、响应客户端请求来修改这些表的函数。开始之前请确保你已安装 SpacetimeDB 并登录开发者身份。6.3 定义引入与教程代码系列中首次引入新类型/函数/方法时写一小段说明它是什么、在本教程中如何被使用并链接到该条目的参考章节教程涉及写代码时必须在正文中给出完整的最终结果代码。理想情况下读者把文中所有代码块复制拼接起来就能得到一个连贯可运行的程序。若不可能如 C# 需要把整个文件包进一系列作用域就在每个代码块前用一句话说明读者应将其粘贴到哪里连 imports 这类无趣代码也要包含。可以快速带过但要保证让项目跑起来所需的每一行代码都出现在教程里对有趣的代码代码块后要描述它做了什么通常保持简洁提示用户写代码时不要说 copy 或 paste而是用祈使句 add 或 write——这强调主动参与而非被动照抄也隐式鼓励读者按需修改示例代码。6.4 结尾Whats next每个教程都应以类似 Whats next? 的标题结尾包含两部分回顾Tell em what you told em用一两句话提醒读者他们完成了什么如 你刚刚在 SpacetimeDB 中搭起了第一个数据库连同它专属的表和 reducer指引下一步Tell them what to do next若教程属于系列链接下一篇若教程针对特定组件链接其参考页若教程是系列终点或产出完整应用抛出一些读者可以自行扩展的方向如改进终端界面、限制消息订阅范围、给用户表加moderator标志、添加房间/频道、支持私信等完整代码链接教程若涉及写代码应链接到完整代码所在位置自有仓库或现有仓库中的示例项目并确保该目录含 README.md其中包含教程项目名称、如何运行/交互如发布到 maincloud 后用spacetime call、外部依赖链接如客户端项目所依赖的模块、指向构建该项目的教程的反向链接。仓库实证本仓库中的完整模板项目如 templates/chat-console-rs、templates/basic-rs、demo/Blackholio即是教程产出完整可运行代码这一原则的载体而spacetime init预生成的模块骨架见 spacetime dev 指南正是原文档示例中清空server/src/lib.rs里的 trivial 模块写入我们自己的聊天服务器的前提。七、风格规范在仓库中的落地与自检清单这份风格指南并非纸上谈兵仓库中已有多个机制将规范落到实处文档结构即规范docs 站点的内容被组织为 核心概念、资源参考 等区块概览页链接到具体页面、参考页与教程页分层存放与概览页密集链接、参考页分条定义、教程页可拼接运行的三类规范一一对应。LLM 基准工具直接消费文档docs/DEVELOP.md 记录了 LLM 基准测试如何把文档作为上下文喂给模型——它按语言过滤Tabs组件只保留目标语言标签页的内容。这反过来对文档写作提出硬性要求必须使用一致的 tab groupId服务端模块代码用server-language客户端 SDK 代码用client-language、必须为所有受支持语言提供 tab、命名约定要与 golden answer 一致如 C# 表名用 PascalCase。这正是风格指南中表名单数/大小写规范的价值所在——不一致的文档会让自动化评测和读者双双踩坑。内部文档的贴标签实践BSATN、模块 ABI 等页面明确以内部/低级接口定位示人遵循了为高级读者准备、并对更高层系统给出链接的例外条款。给写作者的最终自检清单术语是否与第三节词汇表一致模块 vs 数据库、订阅 vs 一次性查询、Identity vs 用户表名是否单数、是否符合语言的大小写惯例代码块是否都带语言标记元变量是否用{}包裹并附说明参考页是否用陈述式现在时、主动语态是否包含两列表格与签名代码块教程是否声明了范围/目标/前置条件代码能否复制拼接后运行结尾是否有 Whats next?是否坦率标注了当前限制/已知问题而没有对未来的空头承诺把这套纪律内化你就写出了能被人类愉快阅读、也能被搜索引擎与 LLM 准确理解的 SpacetimeDB 文档。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考