Migrate Customer-Facing API to GraphQL

Migrate Customer-Facing API to GraphQL

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

Context

Our REST API has grown to 50+ endpoints with inconsistent patterns...

Decision

Migrate customer-facing API from REST to GraphQL while maintaining REST for internal services.

Rationale

Why GraphQL:

• Clients fetch exactly what they need (no over/under-fetching)
• Single endpoint, self-documenting schema
• Type safety with code generation
• ...

Options Considered

Option A: Keep REST (Status Quo)

Pros: No migration cost, team familiarCons: Doesn't solve core problems, maintenance keeps growingDecision: Rejected - doesn't address root cause

Option B: gRPC

Pros: Performance, strong typingCons: Browser support issues, steeper learning curveDecision: Rejected - better for internal services

Option C: GraphQL

Pros: Solves over/under-fetching, great DX, strong ecosystemCons: Learning curve, caching complexity, migration effortDecision:Accepted

Consequences

Positive: Faster frontend/mobile development; Reduced API maintenance burden; ...Negative: 3-4 month migration timeline; Team needs training; ...

Implementation Plan

1. GraphQL server setup (Apollo Server)
2. Schema design workshop
3. Gradual migration (start with new features)
4. Dual-run period (both REST and GraphQL)
5. Deprecate old REST endpoints

值得注意的细节：**Options Considered 中的每个备选方案都标注了 `Decision: Rejected / Accepted`**，即“考虑过什么”和“为什么否决”被完整留档。这正是原文档最佳实践中“Include alternatives: Show what was considered and why it wasn't chosen”的直接体现。 ## 五、视图配置：五种视角消费决策数据 数据库不仅要能“存得进”，还要能“看得清”。原文档给出了五个内置视图： | 视图 | 配置方式 | 适用场景 | |------|----------|----------| | **Recent Decisions** | 按 Date 降序排序 | 快速了解最新决策动态 | | **Active Decisions** | 过滤 `Status = "Accepted"` | 当前有效决策清单 | | **By Domain** | 按 Domain 分组 | 按领域浏览决策全景 | | **High Impact** | 过滤 `Impact = "High"` | 聚焦高风险重大决策 | | **Pending** | 过滤 `Status = "Proposed"` | 待拍板/待评审的提案 | 这五个视图两两组合就能覆盖绝大多数使用场景：例如“按领域分组 + 过滤 Accepted”即可得到各领域的有效决策地图；“Pending 视图”则是评审会上的天然议程清单。 在 [database-best-practices.md](https://link.gitcode.com/i/ef228379e3cde0c25d578bed37fbcdf3) 中，“Create views for common use cases”被列为维护建议之一——视图不是一次配完就结束，而应随团队使用习惯持续演进。 ## 六、最佳实践：五条黄金法则 原文档给出的五条最佳实践，本质上是让决策日志“活”起来的运营准则： 1. **Document immediately**：在决策做出的当下立即记录，趁上下文还新鲜（context is fresh）。拖延的记录往往丢失关键理由； 2. **Include alternatives**：写明考虑过的备选方案及未选原因，这是 ADR 区别于普通会议纪要的核心； 3. **Track superseded decisions**：决策变化时更新状态。`Superseded` 状态存在的意义就是让旧决策不会误导后人； 4. **Link related decisions**：用 relation 关联相关决策，显式展示依赖关系； 5. **Review periodically**：定期复查旧决策是否仍然有效，保持决策库的新鲜度。 ## 七、在 Codex 中实操：从对话到决策记录的完整闭环 决策日志数据库并不是孤立存在的，它是 [notion-knowledge-capture](https://link.gitcode.com/i/038486e99a0743b33df2404cfe6650a6) 技能包中“知识捕获”能力的一环。完整流程如下。 ### 7.1 前置条件：连接 Notion MCP 该技能依赖 Notion MCP 服务（见 [agents/openai.yaml](https://link.gitcode.com/i/4c390de18274d032dc672e35a1b20fb4) 中的 `dependencies.tools` 声明，传输方式为 `streamable_http`，地址 `https://mcp.notion.com/mcp`）。按 [SKILL.md](https://link.gitcode.com/i/038486e99a0743b33df2404cfe6650a6) 的说明，首次使用需完成三步配置： ```bash # 1. 添加 Notion MCP codex mcp add notion --url https://mcp.notion.com/mcp # 2. 启用远程 MCP 客户端 # 方式 A：在 config.toml 中设置 [features].rmcp_client = true # 方式 B：命令行启用 codex --enable rmcp_client # 3. OAuth 登录 codex mcp login notion

登录成功后需要重启 Codex，技能才能生效。

7.2 五步工作流

按 SKILL.md 的工作流定义，一次决策捕获走五步：

1. Define the capture：明确内容类型是 decision（区别于 how-to、FAQ、wiki）；
2. Locate destination：根据 database-best-practices.md 的选择指南，决策类内容应落入Decision Log数据库：

   | Track decisions | Decision Log |

3. Extract and structure：从对话中提取决策、备选方案、理由与结果；
4. Create/update in Notion：用notion-create-pages写入数据库（使用data_source_id指向决策日志库），页面结构套用本文第四节的六段式模板；
5. Link and surface：添加 relation/反向链接到枢纽页面与相关文档，让决策可被发现。

7.3 工具调用链：search → fetch → create

在 examples/decision-capture.md 中，决策捕获涉及三个 MCP 工具的有序调用：

1) Notion:notion-search query: "architecture decisions" or "ADR" # 查找决策日志库 2) Notion:notion-fetch # 获取数据库 Schema 3) Notion:notion-create-pages # 写入决策记录 parent: { data_source_id: "decision-log-collection-id" }

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills