ArtCraft 代码风格规范深度解析:Rust 约定、文件布局与命名规则

原创2026-10-14 17:50:041,898 阅读
文章标签:AI 应用媒体生成桌面应用人工智能前端

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 文件内部的组织顺序

  1. 常量紧跟在导入之后,位于文件顶部;
  2. 主公共类型(该文件真正围绕其展开的 struct/enum)紧随其后。打开文件的人应立即知道文件定义了什么;
  3. 辅助/从属类型(子结构体、辅助枚举、序列化 DTO)放在主类型下方而非上方。判据是一道反问:"读者在看到主类型之前需要知道这个类型的存在吗?"——不需要就下移;
  4. API 类型的顺序:Request,然后是 Response(成功),最后是 Error;
  5. impl 块跟在类型定义之后。

character_type.rs 是这个顺序的教科书式样本:导入(L1-6)→ 带 doc 注释的主枚举定义(L8-19)→ 宏展开(L21-22)→ impl 块(L24-43)→ #[cfg(test)] mod tests(L45 起)。文件一打开,主类型立刻映入眼帘,细节按重要性递减排列。

2.2 impl 块内部的组织顺序

  1. 构造函数(new、from_*、builder)置顶;
  2. 公共方法其次——它们是读者关心的主入口;
  3. 私有辅助方法在公共方法之下,且辅助方法之间再细分:
    • "有肉"的辅助方法(逻辑厚重、是公共入口的直接延续)排在"叶子"辅助方法(小格式化工具、简单查找)之上;
    • 调用同一文件内其他方法的方法,应出现在被调用方法之上。这让读者可以沿着调用链向下追踪,而不用来回跳转。

这条"调用者在上、被调用者在下"的规则,本质上是在为函数级阅读路径建模:控制流与数据流在垂直方向上保持单调。

2.3 测试模块的组织顺序

原则是"测试用例在前,辅助设施在后"——打开测试文件的人应先看到测什么,再看到测试装置怎么搭。具体顺序为:

  1. 导入(Imports);
  2. 常量(测试 ID、URL、fixture 数据)——测试引用的小上下文;
  3. 测试函数或按类别分组的子模块;
  4. 辅助函数(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 而言,文档所列技术栈均有对应依赖项可查证:

  • react 18.3.1、react-dom 18.3.1;
  • zustand ^5.0.5(状态管理);
  • three ^0.171.0(3D 渲染);
  • nx 21.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 顺序与两层嵌套测试的文件,把全部规则在同一个样本上对号入座。

登录后查看全文
artcraft