docs/code-style.md

代码风格规范

注释风格

模块文档（//!）

• 第一行：模块职责 —— 具体描述
• 空行后：关键设计决策或限制

//! 账号池管理 —— 多账号负载均衡
//!
//! 1 account = 1 session = 1 concurrency

公有 API 文档（///）

• 使用动词开头："返回"、"创建"、"发送"
• 明确副作用："自动释放"、"清理 session"
• 标注 Panic 条件（如有）

/// 轮询获取一个空闲账号
///
/// 返回的 AccountGuard 在 Drop 时自动释放 busy 标记
pub fn get_account(&self) -> Option<AccountGuard>

行内注释（//）

• 解释"为什么"而非"做什么"
• 标注临时方案或外部依赖

// 顺序很重要：health_check 必须在 update_title 之前，
// 否则空 session 会导致 EMPTY_CHAT_SESSION 错误

命名规范

类型	风格	示例
模块/文件	snake_case	ds_core, accounts.rs
类型/结构体	PascalCase	AccountPool, CoreError
函数/方法	snake_case	get_account(), compute_pow()
常量	SCREAMING_SNAKE_CASE	ENDPOINT_USERS_LOGIN
枚举变体	PascalCase	AllAccountsFailed

错误消息

• 中文：配置验证、账号管理等面向用户的错误消息使用中文
• 英文：内部库错误（ds_core、client、adapter、anthropic_compat）使用英文，供开发者调试
• 包含上下文："账号 {} 初始化失败"
• 避免泄露敏感信息（token 只打印前8位）
• 服务器层的 ServerError::Display 向 API 客户端展示错误时，保持适配器原始消息不变

枚举变体命名

• 所有枚举变体使用 PascalCase（如 AllAccountsFailed、BadRequest）
• 仅在 serde 序列化时通过 #[serde(rename = "...")] 使用非 PascalCase

日志规范

见 docs/logging-spec.md

导入分组

1. 标准库 (std::)
2. 第三方库 (tokio::, wreq::)
3. 内部模块 (crate::)
4. 本地 use (super, self)

组间空行分隔。

测试代码规范

• 测试函数内部允许使用 println! 输出中间结果，便于失败时观测解析内容
• 库代码（src/ 非 #[cfg(test)] 区域）仍禁止直接使用 println! / eprintln!