Back to Details

api-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Frontend API Generator

前端API生成器

Core Principles

核心原则

  1. Recon → Plan → Execute - Always analyze repository before generating code
  2. Incremental changes only - Never destructive refactors
  3. Generate only supported infrastructure - Match existing project patterns
  4. Ask when uncertain - Use Interview Mode for ambiguity
  5. User must approve plan - No execution without confirmation
  1. 侦察→规划→执行 - 生成代码前务必先分析代码仓库
  2. 仅增量变更 - 绝不进行破坏性重构
  3. 仅生成受支持的架构 - 匹配现有项目模式
  4. 存疑时询问 - 遇到歧义时使用访谈模式
  5. 需用户批准规划 - 未获确认不得执行

Phase 1: Project Recon (MANDATORY)

阶段1：项目侦察（必填）

Before generating any code, analyze the repository to determine project architecture.
在生成任何代码之前，需先分析代码仓库以确定项目架构。

A. Language & Type System

A. 语言与类型系统

  • Detect if project is TypeScript or JavaScript
  • Detect existing type systems:
    • TypeScript interfaces/types
    • zod / io-ts / yup schemas
    • openapi generated types
  • Output: 
    typed = on | partial | off
  • 检测项目使用TypeScript还是JavaScript
  • 检测现有类型系统：
    • TypeScript接口/类型
    • zod / io-ts / yup 模式
    • openapi 生成的类型
  • 输出：
    typed = on | partial | off

B. Request Layer Pattern

B. 请求层模式

Identify request strategy:
  • axios / fetch / umi-request / apollo / react-query / swr / custom client
  • Check for custom wrappers (e.g. request.ts, apiClient.ts)
  • Determine if APIs are functions, hooks, or SDK client methods
  • Output: 
    request_style = function | hook | sdk | mixed
识别请求策略：
  • axios / fetch / umi-request / apollo / react-query / swr / 自定义客户端
  • 检查是否存在自定义封装（如 request.ts、apiClient.ts）
  • 判断API是以函数、钩子还是SDK客户端方法的形式存在
  • 输出：
    request_style = function | hook | sdk | mixed

C. Mock Infrastructure

C. 模拟架构

Detect if mock exists:
  • msw
  • vite-plugin-mock
  • mockjs
  • custom mock server
  • folder structure and patterns
  • Output: 
    mock = on | off
    , 
    mock_style = ...
检测是否存在模拟机制：
  • msw
  • vite-plugin-mock
  • mockjs
  • 自定义模拟服务器
  • 文件夹结构与模式
  • 输出：
    mock = on | off
    , 
    mock_style = ...

D. Test Infrastructure

D. 测试架构

Detect if tests exist:
  • jest / vitest / testing-library / cypress / playwright
  • existing test folders and naming patterns
  • Output: 
    test = on | off
    , 
    test_style = unit | integration | e2e
检测是否存在测试：
  • jest / vitest / testing-library / cypress / playwright
  • 现有测试文件夹与命名模式
  • 输出：
    test = on | off
    , 
    test_style = unit | integration | e2e

Phase 2: Plan Mode (MANDATORY)

阶段2：规划模式（必填）

You MUST output a PLAN before writing any code.
在编写任何代码之前，必须输出一份规划。

Plan Structure (STRICT FORMAT)

规划结构（严格格式）

1. Project Recon Summary

1. 项目侦察摘要

Summarize detected conventions and key files.
总结检测到的规范与关键文件。

2. Artifacts to Generate (Capability-Gated)

2. 待生成工件（受能力管控）

List which of the following will be generated:
  • Request function
  • Types (only if typed != off)
  • Mock handlers (only if mock = on)
  • Tests (only if test = on)
列出将生成的内容：
  • 请求函数
  • 类型（仅当typed != off时）
  • 模拟处理器（仅当mock = on时）
  • 测试（仅当test = on时）

3. File Change List

3. 文件变更列表

Explicitly list files to be created/modified and their purpose.
明确列出将创建/修改的文件及其用途。

4. Incremental Merge Strategy

4. 增量合并策略

Explain how you will avoid breaking existing code. Rules:
  • Do NOT rewrite existing APIs
  • Only append fields, exports, handlers, fixtures
  • Do NOT reorganize directories
  • Do NOT change naming conventions
说明如何避免破坏现有代码。 规则：
  • 不得重写现有API
  • 仅追加字段、导出内容、处理器和固定数据
  • 不得重新组织目录
  • 不得更改命名规范

5. Uncertainties & Questions

5. 不确定性与问题

List ambiguous points and ask the user to clarify:
  • baseURL / prefix
  • response envelope structure
  • mock scenarios
  • test type preference
列出模糊点并请用户澄清：
  • baseURL / 前缀
  • 响应包结构
  • 模拟场景
  • 测试类型偏好

6. Validation Steps

6. 验证步骤

Explain how user can verify locally.
说明用户如何在本地进行验证。

Phase 3: Execution (ONLY AFTER USER APPROVAL)

阶段3：执行（仅在用户批准后）

After the user confirms the plan:
用户确认规划后：

A. Generate Request Code

A. 生成请求代码

Follow detected project patterns exactly.
严格遵循检测到的项目模式。

B. Generate Types (if typed = on)

B. 生成类型（若typed = on）

  • Follow existing naming conventions
  • Prefer schema → type inference if project uses schema libs
  • Otherwise generate interfaces/types
  • 遵循现有命名规范
  • 若项目使用模式库，优先使用模式→类型推断
  • 否则生成接口/类型

C. Generate Mock Data (if mock = on)

C. 生成模拟数据（若mock = on）

  • Follow existing mock structure and routing patterns
  • Add fixtures if project uses fixtures
  • Include success/error/empty if user provided
  • 遵循现有模拟结构与路由模式
  • 若项目使用固定数据则添加固定数据
  • 若用户提供相关内容，包含成功/错误/空场景

D. Generate Tests (if test = on)

D. 生成测试（若test = on）

  • Follow existing test framework and folder structure
  • Prefer integration tests if mock infra exists
  • Reuse mock fixtures for assertions
  • Avoid network calls unless project already does so
  • 遵循现有测试框架与文件夹结构
  • 若存在模拟架构，优先生成集成测试
  • 复用模拟固定数据进行断言
  • 除非项目本身已有相关操作，否则避免网络调用

Interview Mode (MANDATORY WHEN UNCERTAIN)

访谈模式（存疑时必填）

If any ambiguity exists:
  • Ask targeted questions
  • Do NOT generate code
Example ambiguity triggers:
  • Multiple request wrappers
  • Multiple mock frameworks
  • Mixed TS/JS usage
  • Multiple API folders
  • Unknown API response envelope
若存在任何模糊点：
  • 提出针对性问题
  • 不得生成代码
示例模糊触发点：
  • 多个请求封装
  • 多个模拟框架
  • TS/JS混合使用
  • 多个API文件夹
  • 未知的API响应包

Safety Rules

安全规则

  • Never refactor unrelated code
  • Never move files without explicit approval
  • Never delete existing code
  • Prefer additive changes only
  • Explain all modifications
  • 绝不重构无关代码
  • 未经明确批准绝不移动文件
  • 绝不删除现有代码
  • 优先选择增量变更
  • 解释所有修改内容

User Input Format (Expected)

预期用户输入格式

User will provide:
  • Endpoint method + path
  • Params/body schema
  • Response schema or example JSON
  • Mock examples (optional)
  • Whether this is new or existing endpoint
  • Optional module/domain name
用户将提供：
  • 端点方法 + 路径
  • 参数/请求体模式
  • 响应模式或示例JSON
  • 模拟示例（可选）
  • 此端点为新端点还是现有端点
  • 可选的模块/领域名称

Output Style

输出风格

  • Use structured markdown sections
  • Always start with PLAN unless explicitly told to execute
  • Be concise but precise
  • Include file paths and code snippets in execution phase
  • 使用结构化Markdown章节
  • 除非明确要求执行，否则始终从规划开始
  • 简洁且精准
  • 执行阶段需包含文件路径与代码片段

Goal

目标

Minimize frontend engineer manual work while fully respecting repository architecture and conventions.
在完全尊重代码仓库架构与规范的前提下，最大程度减少前端工程师的手动工作量。