ArtCraft 代码风格规范深度解析:Rust 约定、文件布局与命名规则
ArtCraft 代码风格规范深度解析:Rust 约定、文件布局与命名规则
本文以 code-style.md 为主体,系统讲解 ArtCraft 仓库沉淀的 Rust 代码风格约定、文件内部布局顺序、命名规范、导入组织方式以及前端技术栈要求,并结合 rustfmt.toml、schema 枚举源码与 API client 错误类型等真实实现逐一印证这些规则的落地方式。读完后你可以掌握一套可直接用于 Rust 工作区(Rust workspace)的工程化排版与命名方法论,以及它与格式化工具配置之间的配合关系。
一、Rust 风格核心规则
文档的 Rust 部分列出了八条硬性约定,以下逐条展开,并给出仓库中的实现证据。
1. 两空格缩进,由 rustfmt 强制执行
仓库根目录的 rustfmt.toml 直接体现了第一条规则:
# Four spaces is excessive in any language.
# Conserve horizontal space for small laptop screens.
tab_spaces = 2
注释解释了动机:在小型笔记本屏幕上节省水平空间。该配置还包含若干配套约定,理解它们有助于把握项目的排版哲学:
| 配置项 | 取值 | 说明 |
|---|---|---|
tab_spaces |
2 |
两空格缩进,与文档规则一致 |
newline_style |
"Unix" |
仅使用 Unix 换行符 |
match_block_trailing_comma |
true |
match 块尾逗号(注释标注"默认值是错的") |
use_try_shorthand |
true |
注释说明"try! 不应出现在代码库中",统一用 ? 语法 |
use_small_heuristics |
"Off" |
修复方法链换行问题,否则 rustfmt 会把方法链挤成一行 |
max_width / array_width / fn_call_width 等 |
1000 |
放宽宽度上限,减少不必要的强制换行 |
reorder_imports / reorder_modules 等 |
false |
配置中标注 "TEMPORARY",即暂不自动重排,为手工控制导入分组留出手动空间 |
值得注意的是,文档要求"导入分组:std、外部 crate、内部 workspace crate、crate::"。rustfmt.toml 中 group_imports = "StdExternalCrate" 与 imports_granularity = "Item" 两项被注释掉并标注为 nightly-only 特性——也就是说,当前的分组规范是由人工/代码评审维护的,工具链只提供了部分自动化。阅读该文件时能看到这种"规则先行、工具跟进"的演进痕迹。
2. 不锁定 MSRV,自由使用最新 stable 特性
文档明确"No minimum supported Rust version; use latest stable features freely"。这意味着项目不设最低支持 Rust 版本(MSRV),新特性可以随 stable 发布直接采用,降低了语言升级的负担。
3. serde 派生宏的两种写法
- 二进制 crate(binary crates)使用
#[macro_use] extern crate serde_derive;; - 库 crate(library crates)使用
use serde_derive::{Serialize, Deserialize};。
这一区分源于 macro_use 宏的导出范围问题:库 crate 不应依赖宏污染全局作用空间。以 character_type.rs 为例,库 crate 中直接通过 #[derive] 上直接写 Serialize, Deserialize`:
#[derive(Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd, Deserialize, Serialize)]
pub enum CharacterType {
/// Character created via Kinovi / Seedance2Pro.
#[serde(rename = "kinovi_seedance")]
KinoviSeedance,
}
4. 禁用 println!/eprintln!,统一走 log crate
生产代码路径中不允许 println! 或 eprintln!(测试除外),日志必须使用 log crate 的 info!、warn!、error!、debug!、trace! 宏。仓库中 API client 的实际代码正是这样写的,例如 download_media_file.rs:
info!("Downloading media file {} of class {} from CDN: {}", ...);
// ...
warn!("Failed to retrieve response body: {}", err);
这样做的工程价值在于:日志级别可以在运行时统一调控、输出目的地(stderr/文件/远端)集中管理,而不是散落在各处 print 调用里。
5. 错误类型:应用层 anyhow,数据库层 sqlx
文档规定可失败函数在应用代码中使用 anyhow::Result / AnyhowResult;而新的数据库查询应改用 Result<T, sqlx::Error>,让类型化的数据库错误能沿调用链被精确处理,而不是被 anyhow 吞掉来源信息。
关于 SQLx 的进一步约定(文档原文引用了 storyteller-web、mysql_queries 这两个 crate 名):MySQL 查询必须集中在 mysql_queries crate 中编写,应用/服务 crate 不直接写 sqlx::query! / sqlx::query(),而是复用其中的函数。需要说明的是:就当前仓库可见内容而言,crates/schema/database/ 下现存的数据库 schema crate 是 sqlite_tasks,文档中提到的 mysql_queries crate 及其 CLAUDE.md 说明在当前目录树中并未出现——这段规则保留了仓库早期的 MySQL 服务化结构信息,引用时应以仓库当前实际目录为准,并理解为"查询逻辑集中收敛到专门的 database crate"这一原则。
6. 枚举的 Display/Debug:专用宏而非 derive_more
文档要求枚举类型实现 Display/Debug 时统一使用 impl_enum_display_and_debug_using_to_str! 宏,原因很实际:CLion 无法识别 derive_more::Display,会影响 IDE 体验。该宏定义在 impl_enum_display_and_debug_using_to_str.rs,并在 schema 枚举 crate 中被大规模使用(audit_logs、batch_generations、beta_keys、characters 等模块下大量枚举文件都在调用它)。以 character_type.rs 为例:
impl_enum_display_and_debug_using_to_str!(CharacterType);
impl_mysql_enum_coders!(CharacterType);
宏紧跟在枚举定义之后、impl 块之前,与后文"文件布局顺序"规则完全吻合。
7. 可空字段 maybe_ 前缀
可选字段以 maybe_ 前缀命名,例如 maybe_creator_user_token、maybe_prompt_token。仓库中原生桌面端后端代码大量遵循此约定,如 jobs.rs 中的 pub maybe_prompt_token: Option<String>、backend/mod.rs 中的 maybe_prompt_token: None, maybe_generation_provider: None 等调用实参。前缀让"这个字段可能为 None"在函数签名层面一目了然,减少调用方漏传的处理成本。
8. 错误类型的 fmt::Display 统一写法
为错误类型实现 fmt::Display 时固定采用:
write!(f, "{:?}", self)
仓库中 API client 的错误类型普遍如此,例如 gmicloud_client_error.rs、gmicloud_error.rs。借助 Debug 派生直接输出结构化字段,省去了为每个错误枚举手写格式字符串的重复劳动。
二、文件布局:自上而下的阅读顺序
这是文档中最有方法论价值的一节。其核心主张是:让自上而下阅读的人"先遇到最重要的东西,只有好奇时才向下钻取",并用报纸作类比——先标题,再正文,最后才是小字细则。
2.1 文件内部的组织顺序
- 常量紧跟在导入之后,位于文件顶部;
- 主公共类型(该文件真正围绕其展开的 struct/enum)紧随其后。打开文件的人应立即知道文件定义了什么;
- 辅助/从属类型(子结构体、辅助枚举、序列化 DTO)放在主类型下方而非上方。判据是一道反问:"读者在看到主类型之前需要知道这个类型的存在吗?"——不需要就下移;
- API 类型的顺序:Request,然后是 Response(成功),最后是 Error;
impl块跟在类型定义之后。
character_type.rs 是这个顺序的教科书式样本:导入(L1-6)→ 带 doc 注释的主枚举定义(L8-19)→ 宏展开(L21-22)→ impl 块(L24-43)→ #[cfg(test)] mod tests(L45 起)。文件一打开,主类型立刻映入眼帘,细节按重要性递减排列。
2.2 impl 块内部的组织顺序
- 构造函数(
new、from_*、builder)置顶; - 公共方法其次——它们是读者关心的主入口;
- 私有辅助方法在公共方法之下,且辅助方法之间再细分:
- "有肉"的辅助方法(逻辑厚重、是公共入口的直接延续)排在"叶子"辅助方法(小格式化工具、简单查找)之上;
- 调用同一文件内其他方法的方法,应出现在被调用方法之上。这让读者可以沿着调用链向下追踪,而不用来回跳转。
这条"调用者在上、被调用者在下"的规则,本质上是在为函数级阅读路径建模:控制流与数据流在垂直方向上保持单调。
2.3 测试模块的组织顺序
原则是"测试用例在前,辅助设施在后"——打开测试文件的人应先看到测什么,再看到测试装置怎么搭。具体顺序为:
- 导入(Imports);
- 常量(测试 ID、URL、fixture 数据)——测试引用的小上下文;
- 测试函数或按类别分组的子模块;
- 辅助函数(builder、pipeline runner、断言工具)。
配套的组织约定:
- 某个类别有 2 个及以上测试时,才归入子模块(如
mod pricing_tests { ... });单个测试不建子模块; - 嵌套最多两层:
mod tests { mod category { ... } }; - 共享辅助函数放在父模块,子模块通过
use super::*复用。
character_type.rs 的测试部分正是两层嵌套的示范:mod tests 内先 use(含 use super::* 的用法),再进入 mod explicit_checks 子模块容纳具体的 #[test] 函数,测试辅助 assert_serialization 来自父级共享的 crate::test_helpers。
三、命名规范
文档对五类标识符给出了确定性模板:
| 对象 | 模板 | 文档示例 |
|---|---|---|
| Handler 函数 | {verb}_{noun}_handler |
get_health_check_handler、login_handler |
| 错误枚举 | {Feature}Error |
FalWebhookError、HealthCheckError |
| 请求/响应结构体 | {Action}Request / {Action}Response / {Action}SuccessResponse |
— |
| 路径参数结构体 | {Action}PathInfo |
— |
| Builder 结构体 | {Thing}Builder,setter 用 set_ 前缀,并以 build() 收尾 |
— |
这套命名的特点是"类型/函数名自带文档":看到 FalWebhookError 就能定位到 fal webhook 这个功能域,看到 set_xxx + build() 的组合就能预判它是链式构建器。仓库中 API client 的错误文件命名(如 gmicloud_error.rs、gmicloud_client_error.rs)与 {Feature}Error 模板一致,错误文件一律归入各 client 的 src/error/ 目录,目录名本身即约定。
四、导入(Imports)组织规则
- 分组顺序:std → 外部 crate → 内部 workspace crate →
crate::; - 优先
use导入而非行内全限定路径。仅在两种情况允许行内全限定:真正的一次性引用(加导入纯属噪音),或与 std prelude 重名的类型(Result、Option、Error);只要一个符号被引用超过一次,就必须导入; - 优先具名导入而非通配符,例外是
api_doc.rs和测试模块; - 同名冲突用来源 crate 后缀别名,例如:
use enums::...::CommonResolution as CommonResolutionEnum;
use artcraft_router::...::CommonResolution as CommonResolutionRouter;
后缀直接写明来源 crate(Enum / Router),避免在函数签名和函数体里写长全限定路径。这条规则在多 crate 共享类型的大型 workspace 中尤为关键——ArtCraft 的 artcraft_router 与 schema 侧 enums crate 各自持有类型定义,跨 crate 引用 CommonResolution 这类共享枚举时,别名是保持签名可读性的主要手段。
五、MySQL 表结构约定
- 主键
id列必须为BIGINT(20) UNSIGNED,禁止使用有符号 ID; - 建表必须写
ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin。
无符号主键规避了"负数 ID"这一永不合法的状态空间;utf8mb4_bin 的二进制排序规则保证了区分大小写的精确字符串排序,对 token、代码类字段是稳妥选择。这两条属于 schema 层面的不变式(invariant),配合第二节提到的"查询集中在 database crate"原则,构成项目对持久层的完整约束。如前所述,当前仓库 crates/schema/database/ 下的可见实现是 sqlite_tasks(面向本地任务的 SQLite schema crate),MySQL 规则是文档记录的服务端约定,实际落地以仓库现有目录为准。
六、TypeScript / 前端约定
文档对前端的要求简洁明确:
- 技术栈:TypeScript + React、Vite、Zustand、Three.js;
- 两空格缩进。
文档提到这是"位于 crates/frontend/ 下的 Nx monorepo";在当前仓库目录结构中,该 monorepo 位于根目录的 frontend/ 下,阅读时以实际路径为准。就 frontend/package.json 而言,文档所列技术栈均有对应依赖项可查证:
react18.3.1、react-dom18.3.1;zustand^5.0.5(状态管理);three^0.171.0(3D 渲染);nx21.2.3(devDependencies,确认 Nx monorepo 结构);- 另有
@tauri-apps/plugin-http、tauri相关依赖(见 crates/desktop/artcraft 的 Tauri 桌面壳配置),印证了"Web 前端 + Rust 桌面壳"的组合。
frontend/ 内部按 apps/artcraft(应用入口)+ libs/(api、components、state、tauri-api 等领域库)组织,配合 Nx 的项目引用模型实现库级别的分层构建与测试隔离——这与 Rust 侧"crate 边界清晰、职责单一"的约定在架构理念上是同构的。
七、这些规范如何协同工作
把文档各节放回工程视角,可以看到它们解决的是同一类问题:降低多人协作中"读代码"的认知成本。
rustfmt.toml把排版细节(缩进、换行、宽度)交给机器,人不再为此争论;- 文件布局顺序(主类型优先、调用者在上)把"阅读路径"设计成单向流,配合两空格缩进与 1000 列宽,单屏可见行数更多、垂直滚动更少;
- 命名模板(
{Action}Request、{Feature}Error、maybe_前缀)让搜索与预测成为可能:想找 fal webhook 的错误处理,搜FalWebhookError即可; - 导入别名后缀、
maybe_前缀、write!(f, "{:?}", self)这类微观约定,则消除了"同一个东西该叫什么/怎么写"的重复决策。
对希望在该仓库上继续开发或参考其组织方式的读者,建议的切入顺序是:先读 rustfmt.toml 理解机器管住的部分,再读本文第二节的布局规则理解人管住的部分,最后对照 character_type.rs 这样一份同时体现枚举宏、impl 顺序与两层嵌套测试的文件,把全部规则在同一个样本上对号入座。