Skip to content

[refactor] docs: deepen endpoint catalog with request semantics #424

Description

@foxzool

Problem Statement

OpenLark Docs 的端点目录已经集中拥有动态 path,但稳定的请求语义仍泄漏到大量叶子 module:每个叶子独立选择 HTTP method、token 要求、query/body 形态和响应提取。目录测试只证明 path,不证明 method/path 组合;因此目录测试可以全绿,而叶子仍可能以错误 method 调用正确 path。使用者看到的错误通常是运行时 404/405 或响应不匹配,维护者则需要在多个位置理解一个端点。

Solution

把 Docs 端点目录深化为拥有稳定请求语义的 domain module。端点身份、HTTP method、路径参数和稳定认证要求在同一 implementation 中保持 locality;叶子 builder 继续作为用户与测试的 interface,只提供领域数据和可变 request option。先以一个端点密集资源族作为 tracer bullet 验证,再按同一规则扩展。

User Stories

  1. As an OpenLark Docs user, I want each leaf builder to call the correct method and path, so that endpoint drift does not surface at runtime.
  2. As an OpenLark Docs user, I want authentication requirements attached to endpoint identity, so that token selection cannot diverge between sibling leaves.
  3. As an OpenLark Bitable user, I want dynamic identifiers encoded by one domain module, so that path construction remains type-safe.
  4. As an OpenLark SDK maintainer, I want method and path to change together, so that official endpoint updates require one edit.
  5. As an OpenLark SDK maintainer, I want request semantics to stay inside the Docs domain, so that core Transport remains domain-agnostic.
  6. As an OpenLark leaf-builder author, I want to supply domain data without re-declaring stable transport facts, so that a new leaf contains less repeated knowledge.
  7. As an OpenLark test author, I want leaf e2e tests to assert method and path together, so that the public builder interface is the test surface.
  8. As an OpenLark test author, I want endpoint-catalog tests to cover semantic completeness, so that missing method or auth metadata fails early.
  9. As an OpenLark reviewer, I want a small tracer-bullet rollout, so that the pattern is proven before broad migration.
  10. As an OpenLark downstream user, I want existing builder names and fluent calls preserved, so that internal deepening is non-breaking.
  11. As an OpenLark operator, I want request IDs and Transport error context unchanged, so that endpoint refactoring does not reduce observability.
  12. As an OpenLark maintainer, I want a repeatable migration rule for other Docs resources, so that follow-up work is mechanical and reviewable.

Implementation Decisions

  • The Docs domain endpoint catalog owns endpoint identity, HTTP method, dynamic path parameters, and stable access-token requirements.
  • Leaf request builders remain the external caller and test interface; their public construction and fluent methods do not change.
  • Leaf implementation supplies domain query/body data and per-call request options, then delegates stable request semantics to the domain endpoint module.
  • Core Transport remains generic and receives a fully described request; Docs-specific knowledge does not move into core.
  • The first implementation is a tracer bullet in one endpoint-dense Docs resource family that includes at least read, create, update, and delete methods.
  • Expansion beyond the tracer bullet requires the same observable behavior and no new seam per resource.
  • Catalog semantics are compile-time data, not a runtime registry or stringly-typed map.
  • Existing path bytes, serialization shapes, response models, and leaf builder interfaces remain unchanged unless the tracer bullet exposes a documented existing defect.
  • This implements the leaf URL decoupling explicitly left for a separate issue by ADR-0001; it does not reopen navigation-shell design.

Testing Decisions

  • The highest test seam is each migrated leaf builder executed against wiremock.
  • E2e-style tests assert HTTP method, exact path, dynamic path encoding, query/body serialization, auth header behavior, request options, and typed response extraction.
  • Endpoint-catalog tests assert semantic completeness and method/path/auth agreement but do not replace leaf execution tests.
  • Before migration, tracer-bullet tests lock current correct behavior; any discovered mismatch is recorded as a bug rather than silently preserved.
  • Tests assert outgoing requests and returned results only; they do not inspect catalog storage or internal helpers.
  • Prior art is the repository's wiremock leaf tests and endpoint enum URL assertions, combined at the higher leaf-builder seam.

Out of Scope

  • A workspace-wide endpoint migration in one change.
  • Changes to navigation shells or DocsClient helpers covered by ADR-0001.
  • Core Transport middleware or response-model redesign.
  • New public leaf builder methods.
  • Automatic synchronization with Feishu documentation.

Further Notes

  • Earlier wrong-method/wrong-path defects show that path-only tests are insufficient.
  • The deletion test already proves the catalog earns locality for paths; this work increases depth by absorbing stable request semantics that currently leak across the seam.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an AFK agenttype:refactor架构或接口收敛性重构

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions