Openlark Code Standards

OpenLark 代码规范检查（Skill）

适用场景

• 用户要求“检查项目代码规范”
• 新增 API 前想确认实现套路是否一致
• 评审 PR 时需要快速验证是否遵循 OpenLark 既有约定
• 发现模块风格漂移，想做一次统一体检

目标

输出一份可落地的规范检查结果，包含：

• 规范结论（通过/风险）
• 规则-证据对（每条规则附 path:line）
• 风险分级（P0/P1/P2）
• 新 API 最小检查清单（可直接用于 PR Review）

检查范围

覆盖全部 crates/openlark-*（按 AGENTS.md#STRUCTURE 有 18 个业务/基础设施 crate）。

• 重点核审：核心基础设施（openlark-core、openlark-client、openlark-protocol）与高频业务 crate（openlark-docs、openlark-communication、openlark-hr）。
• Client 命名（XxxClient）权威映射表见 docs/CLIENT_NAMING_CONVENTION.md 的「当前映射」，命名核审以此为准。
• 可按参数缩小为某个 crate 或目录（如 openlark-mail、crates/openlark-hr/src/）。

核心检查项

1) API 实现套路一致性

• 是否使用 Request/Response + Builder 模式
• 是否提供 execute() 与 execute_with_options(RequestOption)
• 是否通过 Transport::request(...) 发送请求

🔴 硬规则（grep 命中即 P0 违规）：

• 业务 crate（除 openlark-core 与 openlark-webhook）不得出现 reqwest::Client::new()——一旦命中，说明有端点绕过了 Transport，必为不一致源头。检查命令：

  rg "reqwest::Client::new" crates/ --type rust -g '!openlark-core/**' -g '!openlark-webhook/**'

• 白名单说明：openlark-webhook 是有意例外——自定义机器人不是飞书开放平台 API（目标 URL 为用户配置的绝对地址、用 URL 携带签名密钥鉴权、响应体为非标准 {code,msg}），不适用 Transport 的 /open-apis/ 基址与 token 注入，故保留独立 reqwest 路径（见 issue #214 调研结论，注释位于 crates/openlark-webhook/src/robot/v1/send.rs:13-26）。勿改 webhook 的 reqwest 用法。
• 不得手工 Authorization 头 / get_app_token（token 由 Transport 自动注入）
• Service/Request 不得持有 HTTP client 字段（只持 Config）

🟡 R 语义检查（防止双重嵌套陷阱）：

• ApiRequest<R> 的 R 应是响应 data 字段的内容类型，不是外层包装。
• 可疑信号：某个 XxxResponse struct 带 data: Option<...> 字段、同时又作为 ApiRequest<XxxResponse> 的泛型——大概率双重嵌套（core 已把 R 当作 data 内容解析）。
• 详细契约见 Skill(openlark-api) 的"🔒 核心契约"。

2) 端点定义规范

• 是否使用 per-crate 类型安全端点枚举：每个 crate 在 src/common/api_endpoints.rs 定义各自的 <Domain>ApiV1 枚举，并实现 pub fn to_url(&self) -> String（注意 to_url() 返回的是相对路径 String，形如 /open-apis/mail/v1/...，不带基址）。
• 是否避免手写业务 URL（统一走枚举 to_url()）
• 命名注意：枚举名是 <Domain>ApiV1，Domain 通常但并非总是等于 crate 名——以现况为准：
  • 与 crate 同名：MailApiV1（crates/openlark-mail/src/common/api_endpoints.rs:5）、DocsApiV1（crates/openlark-docs/src/common/api_endpoints.rs:440）、HelpdeskApiV1、AppApiV1（application）。
  • 与 crate 名不同：VcApiV1（meeting，crates/openlark-meeting/src/common/api_endpoints.rs:224）、TaskApiV1/BoardApiV1（workflow）、AdminApiV1（platform）、AuthenApiV1（auth）、HR 多枚举（AttendanceApiV1/HireApiV1/OkrApiV1/...）、Docs 多枚举（BitableApiV1/WikiApiV1/DocxApiV1/MinutesApiV1/...）。
• 新增端点时改枚举与 to_url() match 分支，不要在 Request/Builder 里手写 URL 字面量。

3) 参数校验规范

• 必填校验是否统一用 openlark_core::validate_required!
• 字符串是否优先 trim() 后再校验
• 列表字段是否校验非空与长度上限（如 validate_required_list!）

🟡 Token 类型与 Config 形态：

• token 类型是否与接口文档「请求头 → Authorization」标注一致——ApiRequest 默认 [User, Tenant]；仅当文档要求 app_access_token（→ App）等非默认凭证时才显式 .with_supported_access_token_types(...)。注意 App = app_access_token ≠ tenant_access_token（→ Tenant），不要把要求 tenant_access_token 的接口设成 App（详见 #511）。
• Request/Service 是否用 owned Config（非 Arc<Config>）——新代码与重构以 owned 为准（openlark-docs 历史用 Arc 属例外）。

🟡 RequestOption（单数）vs RequestOptions（复数）切勿混用：

• openlark_core::req_option::RequestOption（单数，crates/openlark-core/src/req_option.rs:7）——Transport/execute_with_options 实际接受的类型（token、tenant_key、file_upload/download 等运行时请求控制），业务 crate 调用 execute_with_options(RequestOption::default())。
• openlark_client::types::client::RequestOptions（复数，crates/openlark-client/src/types/client.rs:180）——高级客户端的 timeout/retry_count/headers 构造参数，语义不同。
• 二者字段集合完全不同，不得互相替代或导出混名；业务 crate 写 Builder 时用单数 RequestOption。

4) 命名与公开 API 表达

• Client/Service/Resource/Request/Builder 命名是否语义清晰
• 对外入口是否统一（避免同义入口并存）
• meta 调用链命名是否与仓库约定一致

5) 导出与 feature gating

• mod.rs 与 prelude 是否完整导出新增 API
• Cargo.toml feature 与 #[cfg(feature = "...")] 是否对齐
• 是否存在导出但不可编译或不可访问路径