openlark-api

OpenLark API 接口实现规范（速查）

🧭 技能路由指南

本技能适用场景：

• 添加/重构单个飞书开放平台 API
• 需要确定 API 落盘路径（bizTag → crate → 文件路径）
• 需要参考代码模板（Body/Response + Builder）
• 需要了解端点规范、RequestOption 约定、Service 链式调用

其他技能：

• 字段核对 / 抓飞书文档（playwright）→ Skill(openlark-api-field-verify)（读文档唯一入口）
• 项目级规范体检（架构/API/导出/校验一体）→ Skill(openlark-code-standards)
• 审查整体设计规范 → Skill(openlark-design-review)
• 统一 validate() 写法 → Skill(openlark-validation-style)
• 覆盖率（文件在不在）→ Skill(openlark-api-validation)

关键词触发映射

• 新增 API、重构 API、Builder、Request/Response、mod.rs 导出、RequestOption → openlark-api
• 字段核对、文档抓取、playwright、飞书文档字段 → openlark-api-field-verify
• 代码规范、规范检查、风格一致性、体检 → openlark-code-standards
• 架构设计、public API、收敛方案、feature gating、兼容策略 → openlark-design-review
• validate、必填校验、validate_required、空白字符串、校验聚合 → openlark-validation-style
• 覆盖率、缺失 API、实现数量、CSV 对比、验证脚本 → openlark-api-validation

双向跳转规则

• 读文档 / 字段核对：一律转 openlark-api-field-verify（勿用本技能下的 fetch_docpath.py 在线抓取）。
• 实现完成后必须跑字段核对门禁（见 §0 步骤 8 / §4）；差异修正仍在本技能落地。
• 若实现问题本质是架构范式冲突（Request/Service 边界），转 openlark-design-review。
• 若实现前需要先做全仓规范体检，先跑 openlark-code-standards。
• 若实现完成后要核验覆盖率与缺失清单，转 openlark-api-validation。

---

本文件只保留"可执行的最小流程"。标准示例见 references/；官方文档抓取见 Skill(openlark-api-field-verify)。

🔒 核心契约（所有 crate 必须遵守，不可违反）

这些是仓库唯一规范，违反任何一条都会导致接口不统一/调用失败。完整正确模板见 references/standard-example.md。

1. 新代码默认 config: Config（owned）；现有 Arc<Config> 的 Service/Client 保持现状，勿为统一所有权单独重构。openlark_core::Config 内部已 Arc<ConfigInner>，clone 廉价。新 Request/Service 默认用 config: Config，构造用 Config::build()（直接返回 Config，不要 .unwrap()）。但仓库现有 573+ 文件仍用 Arc<Config>（如 openlark-docs 的 DocsClient/BaseClient/CcmClient，见 crates/openlark-docs/src/common/chain.rs:611-629）——这些保持现状，不为统一所有权单独重构。两种形态都不持 HTTP client，"走 Transport"是硬约束。

2. R（ApiRequest<R> 泛型）是响应 data 字段的内容类型，不是包装层。Transport::request 返回 ApiResponse<R> = {code,msg,data: R,...}，resp.data: Option<R>。

   • 无 schema/透传：R = serde_json::Value，execute 返回 SDKResult<serde_json::Value>。
   • 有 schema：R 就是 data 内容的 typed struct，并 impl ApiResponseTrait { fn data_format() -> ResponseFormat::Data }。
   • ❌ 禁止写成 XxxResponse { data: Option<T> } 外面再包一层——core 已自动把 R 当作 data 内容解析，再包会双重嵌套（运行时才暴露，极难发现）。