openlark-naming_skill

Overview

This skill defines clear naming and public API conventions for the OpenLark Rust SDK, covering Client, Service, Resource, Request, and Builder patterns. It helps teams add or refactor public types, design meta call chains, and resolve naming collisions or inconsistent calling styles in the SDK.

How this skill works

The skill inspects type responsibilities and enforces a decision-first approach: choose the role (Client/Service/Resource) then name accordingly. It validates versioned names, module/typename alignment, and consistent request patterns (Request vs RequestBuilder) to avoid ambiguous re-exports and API usage mismatches. It provides concrete rename templates and a pre-rename checklist for safe refactors.

When to use it

• Designing or renaming public types (pub struct/pub type/re-exports/prelude).
• Implementing meta call chains like client.xxx.v1.yyy.zzz.
• Refactoring SDK modules after discovering same-name Services or semantic drift.
• Adding a new API surface or introducing versioned endpoints.
• Preparing releases that include public API reorganizations.

Best practices

• Decide type responsibility before naming: Client = facade/config holder, Service = executable capability, Resource = namespace node.
• Include version tokens in type names (e.g., DriveV1Service) to prevent use/import conflicts.
• Keep module path and type name aligned so the name signals its module and business area.
• Choose one request style per crate/tree: either XxxRequestBuilder with execute(&Service) or self-contained XxxRequest::new(...).
• Avoid using *Service for pure namespace nodes; prefer *Resource for grouping and config passthrough.
• Run the rename checklist: path→name inference, prelude/re-export conflict check, clear Client/Service/Resource roles, and version name consistency.

Example use cases

• Refactor openlark-docs where multiple DocsService types create import ambiguity by renaming inner versions to DocsV1Service.
• Introduce a top-level BotClient that holds Arc<Config> and exposes bot.v1: BotV1Client as fields.
• Replace intermediate names like CardService with CardResource when the type only groups fields and passes config.
• Standardize all request implementations in a crate to the Builder pattern so .execute_with_options(&service) becomes uniform.
• Rename ccm::doc::DocsService to DocService or LegacyDocService to match module semantics and avoid doc examples confusion.