AI 生码 - API2Code：接口智能匹配与 API 自动化生码全链路设计

C澒2026-04-29 19:34

引言

当前前端业务迭代提速，页面与接口人工匹配低效、接口层代码重复编写、研发效能缺乏量化依据等问题，成为研发效率提升的核心瓶颈。为破解这一痛点，API2Code 平台一期依托 AI 智能能力，构建页面-接口关联、自动化生码及效能指标统计的全流程自动化方案，降低重复劳动，提升前端研发规范性与效率。本文作为一期技术方案，明确核心设计、业务流程及实现细节，为技术对接落地提供参考。

一、核心功能目标

API2Code 一期聚焦业务闭环，实现从资源管理到指标量化的全流程支撑，核心功能如下：

  • 资源可视化管理：搭建页面池、接口池，支持资源增删改查基础操作，实现可视化管控。
  • AI 智能匹配：通过 AI Agent 自动匹配页面与接口，支持人工调整，同步记录匹配准确率。
  • 自动化生码：基于确认的页面-接口关联关系，生成标准化接口层代码，记录生码准确率。
  • 代码一键下载：支持将生成的接口层代码一键下载至本地，直接复用，提升研发效率。
  • 效能指标统计：自动化统计匹配准确率、代码投产率等核心指标，为效能优化提供数据支撑。

二、整体架构设计

采用分层架构设计，遵循职责解耦原则，分为应用层、服务层、基础层，集成外部依赖与 AI 能力，保障系统扩展性、稳定性与易用性，架构如下：
外部依赖与AI能力
调用
调用
对接
调用
基础层
DB数据库
服务层
接口池管理
页面池管理
匹配管理
生码管理
日志版本管理
效能指标计算
应用层
UAT合并监测
插件
YAPI接口平台
AI Agent智能模块

三、核心用例设计

明确研发人员核心操作场景，覆盖资源管理、匹配、生码、下载全流程，用例如下：
页面资源池维护
接口资源池维护
页面-接口关联匹配
代码生成与交付
开发者
触发代码生成
生成接口层代码
生码准确率
下载代码
获取生成的接口代码
AI智能匹配
页面与接口关联匹配
人工调整匹配结果
更新匹配结果
匹配准确率
接口管理操作
接口增删改维护
输入JIRA单号
从资源池拉取关联接口列表
新增页面
添加页面至资源池
更新文件路径
维护页面文件路径
输入JIRA单号
从资源池拉取关联页面列表

四、核心业务流程图

梳理匹配、生码、API 全集获取三大核心业务流程，明确环节逻辑、异常处理与状态流转，确保流程可追溯、可管控。

4.1 匹配流程

否
是
否
是
否
是
是
否
用户点击匹配按钮
前端读取本地页面源码
文件存在?
提示文件不存在
调用/match接口，校验页面状态
状态允许匹配?
返回错误提示
更新页面状态为 matching
获取接口池，调用 AI Agent 匹配
匹配成功?
重置状态为 idle，返回错误提示
保存匹配结果，更新状态为 matched
返回结果，前端渲染展示
用户可调整匹配关系
是否调整?
调用/page/update接口，保存调整结果
流程完成

4.2 生码流程

否
是
否
是
否
是
否
是
否
是
否
是
用户点击生码按钮
前端校验匹配接口
有匹配接口?
提示先完成匹配
前端读取本地页面源码
文件存在?
提示文件不存在
调用/gen_code接口，校验页面状态
状态为 matched?
返回错误提示
校验匹配接口有效性
有有效匹配接口?
更新页面状态为 generating
获取接口列表，同步 YAPI 最新元信息
元信息获取成功?
调用 AI Agent 生码
生码成功?
重置状态为 matched，返回错误
保存生码结果及记录，更新状态为 generated
返回生成的代码

4.3 API 全集获取流程

否
是
用户请求/api/list接口

从YAPI拉取最新接口清单
拉取成功?
返回异常提示信息
与数据库接口比对

识别增删改变动
执行处理：

新增/标记删除/更新接口
合并人工添加的

自定义接口
生成操作通知
返回合并后的

接口列表与通知

五、页面状态机设计

定义页面全生命周期状态及流转条件，规范匹配、生码操作，避免并发冲突，保障流程有序进行，状态机如下：
页面创建完成（初始状态）
触发 AI 匹配（开始匹配）
匹配成功
匹配失败
触发代码生成（开始生码）
生码成功
生码失败
start
idle
matching
matched
generating
generated
空闲状态，可执行匹配操作
匹配中，不允许其他操作
匹配完成，可执行生码操作
生码中，不允许其他操作
生码完成，可执行下载操作

六、核心业务时序图

梳理用户、前端插件、Server、YAPI 平台、AI Agent、数据库六大参与者的交互时序，明确接口调用与数据流转逻辑，时序图如下：
数据库 AI Agent YAPI平台 Server 前端插件 用户 数据库 AI Agent YAPI平台 Server 前端插件 用户 输入 JIRA 号 GET /page/list（查页面） 查询页面数据 返回页面列表 返回页面池 GET /api/list（查接口） 获取接口数据 返回接口列表 同步接口数据（增删改） 返回接口池+通知 点击匹配按钮 同步最新 API 列表 读取本地页面源码 POST /match（请求匹配） 检查页面状态 返回页面状态 调用 AI 匹配接口 返回匹配结果 保存匹配结果 返回匹配结果 显示匹配结果 调整匹配关系 POST /page/update（更新匹配） 保存调整结果 返回成功 提示调整完成 点击生码按钮 同步最新 API 列表 读取本地页面源码 POST /gen_code（请求生码） 检查匹配关系 返回匹配数据 获取接口元信息 返回接口元信息 调用 AI 生码接口 返回生成代码 保存生成代码 返回代码树 显示代码预览 点击下载，选择保存路径 GET /download_code（查代码） 查询生成代码 返回代码树 返回代码树 写入指定目录

七、数据库设计

本章设计 api2code 系统数据库表结构，分为核心业务表和指标统计表两大类，核心业务表存储页面、接口、匹配及生码等基础业务数据，指标统计表用于效能分析，所有表均保证关联清晰、查询高效。

7.1 核心业务表

核心业务表支撑系统全流程业务运转，记录页面、接口及二者关联、生码、下载等核心数据，各表通过主键外键关联，形成完整业务链路。

7.1.1 页面表（api2code_pages）

核心作用：存储页面基础信息及生命周期状态，关联 JIRA 需求，作为匹配、生码的基础载体。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 自增主键
jira_id VARCHAR(50) 是 - 关联 JIRA 需求号
page_name VARCHAR(255) 是 - 页面名称
page_file_path VARCHAR(500) 否 NULL 页面文件路径
page_status ENUM 是 'idle' 页面生命周期状态：idle(空闲)、matching(匹配中)、matched(匹配完成)、generating(生码中)、generated(生码完成)
page_source_code TEXT 否 NULL 页面源码内容，用于 AI 匹配和生码
created_at DATETIME 是 CURRENT_TIMESTAMP 创建时间
updated_at DATETIME 是 CURRENT_TIMESTAMP 更新时间

索引设计：

  • PRIMARY KEY (id)：主键索引
  • KEY idx_jira_id (jira_id)：按 JIRA 需求筛选页面
  • KEY idx_page_status (page_status)：按页面状态筛选

7.1.2 接口表（api2code_apis）

核心作用：存储接口基础信息，支持 YAPI 同步与人工管理，作为匹配、生码的核心数据来源。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 自增主键
yapi_id INT(11) 否 NULL 关联 YAPI 接口 ID（YAPI 同步时必填）
api_name VARCHAR(255) 是 - 接口名称
api_path VARCHAR(500) 是 - 接口请求路径
http_method VARCHAR(10) 是 - HTTP 方法（GET、POST 等）
api_metadata JSON 否 NULL 接口元信息（参数、响应等）
api_source ENUM 是 'yapi' 来源：yapi(同步)、manual(人工添加)
api_status ENUM 是 'active' 状态：active(有效)、deleted(已删除)
created_at DATETIME 是 CURRENT_TIMESTAMP 创建时间
updated_at DATETIME 是 CURRENT_TIMESTAMP 更新时间

索引设计：

  • PRIMARY KEY (id)：主键索引
  • KEY idx_yapi_id (yapi_id)：关联 YAPI 接口
  • KEY idx_api_path (api_path)：按接口路径查询
  • KEY idx_api_status (api_status)：筛选有效接口

7.1.3 页面-接口关联表（api2code_page_api_relation）

核心作用：记录页面与接口的最终关联关系，作为生码操作的核心依据，支持人工调整。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 自增主键
page_id INT(11) 是 - 关联页面 ID
api_id INT(11) 是 - 关联接口 ID
match_score DECIMAL(5,2) 否 NULL 匹配分数（0 - 100）
match_type ENUM 是 'ai' 匹配类型：ai(智能匹配)、manual(人工匹配)
is_used_for_codegen TINYINT(1) 是 1 是否用于生码：0-否，1-是
created_at DATETIME 是 CURRENT_TIMESTAMP 创建时间
updated_at DATETIME 是 CURRENT_TIMESTAMP 更新时间

索引设计：

  • PRIMARY KEY (id)：主键索引
  • KEY idx_page_id (page_id)、KEY idx_api_id (api_id)：关联查询页面/接口
  • KEY idx_is_used_for_codegen (is_used_for_codegen)：筛选生码关联关系
  • UNIQUE KEY uk_page_api (page_id, api_id)：避免页面与接口重复关联

说明 ：支持一页多接口、一接口多页面关联；仅 is_used_for_codegen=1 的关联参与生码。

7.1.4 匹配记录表（api2code_match_records）

核心作用：记录所有页面-接口匹配尝试的历史详情，用于追溯匹配过程、统计匹配准确率。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 自增主键
page_id INT(11) 是 - 关联页面 ID
api_id INT(11) 是 - 关联接口 ID
match_score DECIMAL(5,2) 是 - 匹配分数（0 - 100）
match_type ENUM 是 'ai' 匹配类型：ai、manual
match_details JSON 否 NULL 匹配详情（JSON 格式）
created_at DATETIME 是 CURRENT_TIMESTAMP 匹配时间
updated_at DATETIME 是 CURRENT_TIMESTAMP 更新时间

索引设计：

  • PRIMARY KEY (id)：主键索引
  • KEY idx_page_id (page_id)、KEY idx_api_id (api_id)：关联查询
  • KEY idx_created_at (created_at)：按时间筛选匹配记录

7.1.5 生码记录表（api2code_code_generation）

核心作用：记录每次生码操作的详情，存储生成的代码树，用于追溯生码过程、统计生码效能。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 自增主键（生码记录 ID）
page_id INT(11) 是 - 关联页面 ID
selected_page_api_ids JSON 是 - 生码所用页面-接口关联 ID 列表（仅 is_used_for_codegen=1）
generated_code_tree JSON 是 - 生成的代码树（JSON 格式）
generated_file_count INT(11) 是 - 生成文件总数
generated_line_count INT(11) 是 - 生成代码总行数
created_at DATETIME 是 CURRENT_TIMESTAMP 生码时间

索引设计：

  • PRIMARY KEY (id)：主键索引
  • KEY idx_page_id (page_id)：按页面查询生码记录

7.1.6 下载记录表（api2code_download_records）

核心作用：记录代码下载操作详情，关联生码记录，用于追溯下载情况、统计投产数据。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 自增主键
page_id INT(11) 是 - 关联页面 ID
generation_id INT(11) 是 - 关联生码记录 ID
download_path VARCHAR(500) 否 NULL 本地下载路径
downloaded_files JSON 否 NULL 下载文件列表（JSON 格式）
created_at DATETIME 是 CURRENT_TIMESTAMP 下载时间

索引设计：

  • PRIMARY KEY (id)：主键索引
  • KEY idx_page_id (page_id)、KEY idx_generation_id (generation_id)：关联查询

7.1.7 计算任务表（api2code_calculation_tasks）

核心作用：记录指标计算任务信息，关联 GitLab Webhook 事件，支撑效能指标异步计算与追溯。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 自增主键（任务 ID）
jira_id VARCHAR(50) 是 - 关联 JIRA 需求号
task_type ENUM 是 - 任务类型：merge_to_version（合并到版本）
status ENUM 是 'pending' 任务状态：pending(待执行)、running(执行中)、success(成功)、failed(失败)
project_id VARCHAR(100) 是 - 项目 ID
mr_id VARCHAR(50) 是 - MR ID
source_branch VARCHAR(255) 是 - 源分支
target_branch VARCHAR(255) 是 - 目标分支
merge_commit_sha VARCHAR(255) 否 NULL 合并 Commit SHA
error_message TEXT 否 NULL 任务失败错误信息
created_at DATETIME 是 CURRENT_TIMESTAMP 任务创建时间
updated_at DATETIME 是 CURRENT_TIMESTAMP 任务更新时间

索引设计：

  • PRIMARY KEY (id)：主键索引，唯一标识每条计算任务记录
  • KEY idx_jira_id (jira_id)：按 JIRA 需求号筛选关联的计算任务
  • KEY idx_status (status)：按任务状态（待执行、执行中等）筛选任务
  • KEY idx_mr_id (mr_id)：按 MR ID 关联查询对应的计算任务

7.2 指标统计表

指标统计表用于存储系统效能分析相关数据，涵盖页面覆盖度、匹配准确率、代码投产率、增量代码占比四类核心指标，支撑系统效能优化。

7.2.1 页面指标表（api2code_page_metrics）

核心作用：存储单个页面的各类效能指标数据，关联核心业务表，用于精准分析页面级效能。

字段名 类型 是否必填 默认值 说明
id INT(11) 是 自增 主键 ID，唯一标识指标记录
page_id INT(11) 是 - 关联页面表主键，绑定具体页面
jira_id VARCHAR(50) 是 - 关联 JIRA 需求号，便于按需求统计
metric_type ENUM 是 - 指标类型：页面覆盖度、匹配准确率、代码投产率、增量代码占比
metric_time DATETIME 是 - 指标计算时间，用于追溯
task_id INT(11) 否 NULL 关联计算任务表，追溯计算任务
match_record_id INT(11) 否 NULL 仅匹配准确率有效，关联匹配记录表
download_id INT(11) 否 NULL 仅代码投产率有效，关联下载记录表
匹配页面覆盖度相关字段（仅 coverage 类型有效）
total_pages INT(11) 否 NULL 需求总页面数
covered_pages INT(11) 否 NULL 工具覆盖页面数
coverage_rate DECIMAL(5,2) 否 NULL 覆盖率
page_detail JSON 否 NULL 页面详细代码（JSON 格式）
匹配准确率相关字段（仅 match_accuracy 类型有效）
total_matches INT(11) 否 NULL 总匹配数，页面与接口匹配尝试总次数
high_score_matches INT(11) 否 NULL 高分匹配数（≥ 80 分），反映高质量匹配
mid_score_matches INT(11) 否 NULL 中分匹配数（50 - 79 分），反映中等质量匹配
low_score_matches INT(11) 否 NULL 低分匹配数（< 50 分），反映低质量匹配
average_score DECIMAL(5,2) 否 NULL 平均匹配分数（保留 2 位小数）
high_score_accuracy DECIMAL(5,2) 否 NULL 高分匹配准确率（保留 2 位小数）
mid_score_accuracy DECIMAL(5,2) 否 NULL 中分匹配准确率（保留 2 位小数）
low_score_accuracy DECIMAL(5,2) 否 NULL 低分匹配准确率（保留 2 位小数）
quality_analysis JSON 否 NULL 匹配质量分析（JSON 格式）
代码投产率相关字段（仅 code_production_rate 类型有效）
similarity_score DECIMAL(5,2) 否 NULL 生成与投产代码相似度（0 - 100，保留 2 位小数）
direct_production_rate DECIMAL(5,2) 否 NULL 直接投产率（0 - 100，保留 2 位小数）
file_match_count INT(11) 否 NULL 与投产代码匹配的文件数
file_total_count INT(11) 否 NULL 生码生成的总文件数
line_match_count INT(11) 否 NULL 与投产代码匹配的代码行数
line_total_count INT(11) 否 NULL 生码生成的总代码行数
lightly_modified_lines INT(11) 否 NULL 轻微修改可投产行数（AST 相似度≥ 90 %）
file_level_stats JSON 否 NULL 文件级别投产统计（JSON 格式）
增量代码占比相关字段（仅 incremental_ratio 类型有效）
diff_total_lines INT(11) 否 NULL 增量代码总行数（排除空行、注释）
diff_types_lines INT(11) 否 NULL 增量代码-类型层行数
diff_api_lines INT(11) 否 NULL 增量代码-接口调用层行数
diff_const_lines INT(11) 否 NULL 增量代码-常量层行数
diff_adapter_lines INT(11) 否 NULL 增量代码-适配层行数
ai_matched_lines INT(11) 否 NULL AI 生成并投产的代码总行数
ai_matched_types_lines INT(11) 否 NULL AI 生成并投产-类型层行数
ai_matched_api_lines INT(11) 否 NULL AI 生成并投产-接口调用层行数
ai_matched_const_lines INT(11) 否 NULL AI 生成并投产-常量层行数
ai_matched_adapter_lines INT(11) 否 NULL AI 生成并投产-适配层行数
ai_code_ratio DECIMAL(5,2) 否 NULL AI 代码占增量代码比例（保留 2 位小数）
types_ratio DECIMAL(5,2) 否 NULL 类型层占增量代码比例（保留 2 位小数）
api_ratio DECIMAL(5,2) 否 NULL 接口调用层占增量代码比例（保留 2 位小数）
const_ratio DECIMAL(5,2) 否 NULL 常量层占增量代码比例（保留 2 位小数）
adapter_ratio DECIMAL(5,2) 否 NULL 适配层占增量代码比例（保留 2 位小数）
diff_files JSON 否 NULL 增量代码涉及文件列表（JSON 格式）
通用字段
created_at DATETIME 是 CURRENT_TIMESTAMP 记录创建时间，自动获取当前时间

索引设计：

  • PRIMARY KEY (id)：主键索引，唯一标识每条页面指标记录
  • KEY idx_page_id (page_id)：按页面 ID 关联查询指标数据
  • KEY idx_jira_id (jira_id)：按 JIRA 需求号筛选指标数据
  • KEY idx_metric_type (metric_type)：按指标类型筛选数据，提升查询效率
  • KEY idx_metric_time (metric_time)：按指标计算时间筛选，支持时间维度统计
  • KEY idx_match_record_id (match_record_id)：关联匹配记录，便于追溯匹配准确率指标来源

八、系统接口设计

本文梳理系统核心接口设计，涵盖页面管理、接口管理、AI 匹配、生码、下载、Webhook 及指标查询七大模块，接口定义规范、格式清晰，可直接用于开发对接。

8.1 页面管理接口

负责页面池增删改查，关联 JIRA 需求号，实现页面信息全生命周期管理。

8.1.1 获取页面列表

接口地址 ：GET /api/codegen/page/list

接口功能：根据 JIRA 需求号查询关联页面列表。

请求参数：

参数名 类型 是否必填 说明
jira_id string 是 JIRA 需求号，用于筛选关联页面

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "pages": [
      {
        "id": 1,
        "jira_id": "CODE-202600188990",
        "page_name": "用户管理页面",
        "page_file_path": "/src/pages/user-management/index.tsx",
        "page_status": "matched",
        "created_at": "2026-04-27 14:30:00"
      }
    ]
  }
}

8.1.2 添加页面到页面池

接口地址 ：POST /api/codegen/page/add

接口功能：将新页面录入系统页面池，完成信息登记。

请求参数：

参数名 类型 是否必填 说明
jira_id string 是 关联的 JIRA 需求号
page_name string 是 页面名称，唯一标识页面
page_file_path string 否 页面文件路径，可选填写

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1
  }
}

8.1.3 更新页面文件路径

接口地址 ：POST /api/codegen/page/update

接口功能：更新页面文件路径或接口匹配结果，保障页面信息准确。

请求参数：

参数名 类型 是否必填 说明
id number 是 页面唯一 ID，指定待更新页面
page_file_path string 否 新的页面文件路径
matches array 否 调整后的页面与接口匹配结果列表

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success"
}

8.2 接口管理接口

负责接口池维护，支持从 YAPI 同步接口及人工增删改，确保接口数据最新可用。

8.2.1 获取接口列表

接口地址 ：GET /api/codegen/api/list

接口功能：查询系统接口池，支持同步 YAPI 最新接口数据。

请求参数：

参数名 类型 是否必填 说明
sync boolean 否 是否同步 YAPI 最新数据，默认 false

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "apis": [
      {
        "id": 1,
        "yapi_id": 88990,
        "api_name": "获取用户列表",
        "api_path": "/api/users",
        "http_method": "GET",
        "api_source": "yapi",
        "api_status": "active"
      }
    ],
    "notifications": [
      {
        "type": "new",
        "count": 5,
        "message": "新增 5 个接口"
      }
    ]
  }
}

8.2.2 管理接口（增删改）

接口地址 ：POST /api/codegen/api/manage

接口功能：人工对接口池接口执行添加、修改、删除操作。

请求参数：

参数名 类型 是否必填 说明
action string 是 操作类型：add（添加）、update（修改）、delete（删除）
id number 否 接口 ID，update/delete 操作必填
api_name string 否 接口名称，add/update 操作必填
api_path string 否 接口路径，add/update 操作必填
http_method string 否 HTTP 请求方法，add/update 操作必填
api_metadata object 否 接口元信息，JSON 格式，可选填写

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1
  }
}

8.3 匹配接口

通过 AI Agent 实现页面与接口智能匹配，返回匹配分数及原因，支撑后续生码操作。

8.3.1 AI 匹配页面和接口

接口地址 ：POST /api/codegen/match

接口功能：调用 AI Agent 分析页面源码，返回页面与接口的智能匹配结果。

请求参数：

参数名 类型 是否必填 说明
id number 是 待匹配的页面 ID
page_source_code string 是 待匹配页面的源码内容

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "matches": [
      {
        "id": 1,
        "api_name": "获取用户列表",
        "api_path": "/api/users",
        "match_score": 85.5,
        "match_details": "页面中包含用户列表展示逻辑"
      }
    ],
    "page_status": "matched"
  }
}

错误响应：

json 复制代码 
{
  "code": 1001,
  "message": "页面状态不允许匹配，当前状态：generating"
}

8.4 生码接口

基于页面与接口匹配结果，自动生成接口层代码，支持下载和投产使用。

8.4.1 生成接口层代码

接口地址 ：POST /api/codegen/gen_code

接口功能：根据页面与接口匹配结果，生成接口层代码并返回生码详情。

请求参数：

参数名 类型 是否必填 说明
id number 是 待生码的页面 ID
page_source_code string 是 页面源码内容，用于生码分析

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "generated_code_tree": {
      "types": {
        "path": "src/api/user/types.ts",
        "content": "export interface User { ... }"
      },
      "api": {
        "path": "src/api/user/api.ts",
        "content": "export const getUserList = () => { ... }"
      }
    },
    "generated_file_count": 4,
    "generated_line_count": 256,
    "page_status": "generated"
  }
}

错误响应：

json 复制代码 
{
  "code": 1002,
  "message": "页面未匹配接口，请先进行匹配"
}

8.5 下载接口

提供生成代码下载能力，返回完整代码树，支持前端本地下载使用。

8.5.1 下载生成的代码

接口地址 ：GET /api/codegen/download_code

接口功能：根据生码记录 ID，获取完整生成代码树，供前端本地下载。

请求参数：

参数名 类型 是否必填 说明
id number 是 生码记录 ID，唯一标识一次生码操作

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "generated_code_tree": {
      "types": {
        "path": "src/api/user/types.ts",
        "content": "export interface User { ... }"
      },
      "api": {
        "path": "src/api/user/api.ts",
        "content": "export const getUserList = () => { ... }"
      }
    }
  }
}

8.6 Webhook 接口

对接 GitLab Webhook 事件，处理分支合并逻辑，触发系统指标自动计算。

8.6.1 GitLab Webhook - 合并到 Version

接口地址 ：POST /api/codegen/webhook/merge_to_version

接口功能：接收 GitLab 合并请求事件，验证分支后触发指标计算任务。

请求参数：

参数名 类型 是否必填 说明
event_type string 是 事件类型，固定为 merge_request
object_attrs object 是 合并请求相关属性
object_attrs.project_id string 是 GitLab 项目 ID
object_attrs.id string 是 合并请求（MR）ID
object_attrs.target_branch string 是 合并目标分支
object_attrs.source_branch string 是 合并源分支
object_attrs.title string 是 合并请求标题
object_attrs.description string 否 合并请求描述
object_attrs.merge_commit_sha string 否 合并提交的 SHA 值

业务逻辑：

  1. 验证分支合法性（仅允许 feature 分支合并至 version 分支）；
  2. 从合并请求中提取 JIRA 需求号；
  3. 创建指标计算任务；
  4. 异步执行指标计算（不阻塞响应）；
  5. 返回任务 ID，供后续查询。

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1
  }
}

8.7 指标查询接口

提供统一指标查询入口，支持多维度筛选，便于查看页面各类效能指标。

8.7.1 统一指标查询

接口地址 ：GET /api/codegen/metrics

接口功能：查询系统所有效能指标，支持按 JIRA 需求、页面、指标类型、时间范围筛选。

请求参数：

参数名 类型 是否必填 说明
jira_id string 否 JIRA 需求号，按需求筛选指标
page_id number 否 页面 ID，按页面筛选指标
metric_type string 否 指标类型：coverage（页面覆盖度）、match_accuracy（匹配准确率）、code_production_rate（代码投产率）、incremental_ratio（增量代码占比）
start_time string 否 开始时间，格式：YYYY-MM-DD HH:mm:ss
end_time string 否 结束时间，格式：YYYY-MM-DD HH:mm:ss

响应格式：

json 复制代码 
{
  "code": 0,
  "message": "success",
  "data": {
    "metrics": [
      {
        "id": 1,
        "page_id": 1,
        "jira_id": "CODE-202600188990",
        "metric_type": "match_accuracy",
        "metric_time": "2026-04-27 14:30:00",
        "total_matches": 10,
        "high_score_accuracy": 80.0,
        "average_score": 75.5
      }
    ],
    "total": 10
  }
}

九、指标计算及后续模块优化

9.1 指标计算总览

9.1.1 核心逻辑

指标计算核心依赖生码文件头部插入的唯一 ID，通过该 ID 建立 AI 生码与待上线 Version 代码的映射关系，结合 Git Diff 数据、生码记录、匹配记录，完成 4 类核心效能指标的自动化统计，整体流程简洁可追溯。

9.1.2 GitLab Webhook 触发流程

触发场景：Feature 分支合并至 UAT 分支时，GitLab Webhook 自动触发指标计算任务，聚焦核心环节，流程如下：
有效
无效
是
否
是
否
是
否
Webhook触发（feature合并至uat）
验证合并事件有效性
提取关联 JIRA 号
任务失败（状态：failed）
JIRA 号提取成功？
创建计算任务（状态：pending）
启动任务（状态：running）
提取页面列表及 Diff 数据
异步计算核心指标 1/2/3/4
计算成功？
结果落库（状态：completed）
重试次数< 3？
延迟重试（状态：retrying）
流程结束

9.1.3 指标计算统一规则

4 类核心指标均以 JIRA 号为关联标识，依赖文件唯一 ID 建立映射关系，统一遵循 "数据提取 - 计算 - 校验 - 落库 / 异常处理" 逻辑，各指标详细计算流程（含流程图）如下。

9.2 核心指标详细说明

9.2.1 指标 1：页面覆盖度

计算流程

是
否
创建计算任务

并启动
查询页面列表

（api2code_pages 表）
遍历所有关联页面
存在成功生码记录

且 download_path 非空？
标记 is_covered = 1

（已覆盖）
标记 is_covered = 0

（未覆盖）
保存指标记录：

metric_type=coverage

核心信息
项目 内容
指标定义 评估 AI 生码对需求页面的覆盖范围，反映需求落地完整性
计算公式 页面覆盖度 = (已覆盖页面数 / 需求下应覆盖页面总数) × 100 %（保留 2 位小数）
触发时机 Feature 分支合并至 Version 分支，与代码直接投产率同步
特殊场景 1. 无关联页面：指标为 null，不保存记录，标记任务异常；2. 部分页面无生码记录：正常统计，未生码页面标记为未覆盖

9.2.2 指标 2：匹配准确率

计算流程

否
是
已下载
未下载
创建计算任务并启动
查询页面列表（api2code_pages 表）
获取 Git Diff 数据
获取最后一次 AI 匹配记录（api2code_match_records 表）
是否存在 AI 匹配记录？
指标为 null，流程结束
是否已下载代码？
策略 1：基于 api2code_page_api_relation 表获取最终匹配结果
策略 2：基于 Git Diff 提取接口路径列表
从 API 快照中删除不存在的接口记录
计算匹配准确率
保存指标记录：metric_type="match_accuracy"
流程结束

核心信息
项目 内容
指标定义 评估 AI 匹配页面与接口的准确性，按匹配分数分层统计
计算公式 匹配准确率 = (准确匹配数 / 总匹配数) × 100 %；分高分（≥ 90 分）、中分（60 - 89 分）、低分（< 60 分）统计分层准确率
触发时机 AI 完成页面 - 接口匹配后立即触发，保障数据实时性

9.2.3 指标 3：代码直接投产率

计算流程

否
是
否
是
创建计算任务并启动
查询页面列表（api2code_pages）
获取 Git Diff 数据
获取最新生码记录（api2code_download_records 表）
存在成功生码记录且已下载？
指标为 null，流程结束
获取生成的代码树 code_tree
遍历生成的每个文件
路径处理与匹配：download_path + 文件相对路径
在 Git 中找到对应文件？
标记该文件投产率为 0
代码对比算法：字符串/AI 对比，清除空行注释
计算文件级别投产率
累计统计投产数据
计算总体投产率
保存指标记录：metric_type="code_production_rate"
流程结束

核心信息
项目 内容
指标定义 评估 AI 生码的实际可用性，是衡量 AI 生码价值的关键指标
计算公式 直接投产率 = (AI 生成并投产的代码行数 / AI 生成的总代码行数) × 100 %（保留 2 位小数）
触发时机 Feature 分支合并至 Version 分支，由 GitLab Webhook 触发
特殊场景 1. 代码未下载：指标为 null，不保存记录；2. 文件名修改：按文件唯一 ID 匹配，不受影响；3. 生码未被使用：投产率为 0 %
备用方式 直接匹配 AI 生码与 Git Diff 内容，仅用于辅助分析，不作为核心数据

9.2.4 指标 4：AI 代码占增量代码的比例

计算流程

否
是
创建计算任务并启动
查询页面列表（api2code_pages）
获取 Git Diff 数据
指标 3 是否计算成功？
指标为 null，流程结束
从指标 3 提取 AI 生码投产行数(按文件分类)
从 Git Diff 计算增量代码行数(清除空行注释)
计算 AI 代码占比(按文件分类)
保存指标记录：metric_type="incremental_ratio"
流程结束

核心信息
项目 内容
指标定义 衡量 AI 生码对整体开发工作量的贡献度，统计 AI 投产代码在增量代码中的占比
计算公式 AI 代码占比 = (AI 生成并投产的代码行数 / 增量代码总行数) × 100 %（保留 2 位小数）
触发时机 与指标 3 一致，Feature 分支合并至 Version 分支时触发
特殊场景 1. 指标 3 为 null：指标 4 也为 null，不保存记录；2. AI 投产行数为 0：占比为 0 %，正常保存

9.3 AST 对比实现

为提升代码相似度判断准确性，引入 AST（抽象语法树）对比方案，核心设计如下：

9.3.1 依赖项

bash 复制代码 
npm install @babel/parser @babel/traverse

9.3.2 核心逻辑与代码

核心逻辑：解析代码生成 AST，标准化节点（消除变量命名、格式等冗余差异），通过节点类型分布与结构相似度，计算综合相似度（0 - 100 分）。

typescript 复制代码 
import { parse } from '@babel/parser';
/**
 * 标准化 AST 节点，保留核心逻辑，消除冗余差异
 * @param node 原始 AST 节点
 * @param varMap 变量名映射表（统一变量命名）
 */
function normalizeAst(node: any, varMap: Map = new Map()): any {
  if (!node || typeof node !== 'object') return node;
  const normNode: any = { type: node.type };
  switch (node.type) {
    case 'Identifier':
      const origName = node.name;
      if (!varMap.has(origName)) varMap.set(origName, `var_${varMap.size}`);
      normNode.name = varMap.get(origName);
      break;
    case 'Literal':
      normNode.value = node.value;
      normNode.raw = String(node.value);
      break;
  }
  return normNode;
}

// 辅助函数（精简注释，按需实现）
// 提取 AST 所有节点
// function extractAstNodes(node: any): any[] { ... }
// 统计 AST 节点类型分布
// function countAstNodeTypes(nodes: any[]): Map<string, number> { ... }
// 计算节点类型分布相似度
// function calcTypeSimilarity(typeCount1: Map<string, number>, typeCount2: Map<string, number>): number { ... }
// 计算 AST 结构相似度（基于最长公共子序列）
// function calcStructureSimilarity(nodes1: any[], nodes2: any[]): number { ... }
// 判断两个标准化 AST 是否完全匹配
// function isAstMatch(ast1: any, ast2: any): boolean { ... }

/**
 * 计算两段代码 AST 相似度（0 - 100，保留 2 位小数）
 * @param code1 待对比代码 1
 * @param code2 待对比代码 2
 */
function calcAstSimilarity(code1: string, code2: string): number {
  try {
    const ast1 = parse(code1, { sourceType: 'module' });
    const ast2 = parse(code2, { sourceType: 'module' });
    const normAst1 = normalizeAst(ast1, new Map());
    const normAst2 = normalizeAst(ast2, new Map());
    
    // 辅助函数（extractAstNodes、calcTypeSimilarity 等按需实现）
    const nodes1 = extractAstNodes(normAst1);
    const nodes2 = extractAstNodes(normAst2);
    if (nodes1.length === 0 && nodes2.length === 0) return 100;
    if (nodes1.length === 0 || nodes2.length === 0) return 0;
    const typeSimilarity = calcTypeSimilarity(countAstNodeTypes(nodes1), countAstNodeTypes(nodes2));
    const structureSimilarity = calcStructureSimilarity(nodes1, nodes2);
    return Number((typeSimilarity * 0.3 + structureSimilarity * 0.7).toFixed(2));
  } catch (error) {
    return 0;
  }
}

9.3.3 轻微修改定义

AST 对比场景下，代码相似度的判断标准调整如下：

  • 定义：两段代码在 AST 层面的相似度 ≥ 90 %，即认为代码逻辑一致；
  • 判断方法：通过解析代码生成 AST，标准化后对比节点类型分布和结构匹配度，计算综合相似度；
  • 示例：
  • const a = 1 和 const a=1 → AST 结构完全一致，相似度 100 %；
  • const a: number = 1 和 const a = 1 → AST 存在类型注解差异，相似度约 85 %。

十、总结

10.1 核心功能回顾

API2Code 一期聚焦前端研发效能提升，构建"资源管理-智能匹配-自动化生码-效能量化"完整业务闭环，各核心模块功能简洁明确、各司其职：

功能模块 核心说明
页面池管理 以 JIRA 需求为核心，实现页面全生命周期管理，存储页面源码、状态等关键信息，为后续操作提供基础。
接口池管理 同步 YAPI 接口数据，支持人工维护，自动识别接口变更并推送通知，保障接口数据实时可用。
AI 智能匹配 依托 AI Agent 分析页面源码，完成页面与接口智能匹配，支持人工调整，记录匹配历史。
自动化生码 基于匹配关系，生成标准化接口层代码，记录生码详情，确保代码可直接复用。
代码下载 支持一键下载生成代码，可直接写入本地指定路径，减少人工冗余操作。
效能指标统计 自动计算四大核心指标，为效能优化提供数据支撑。

10.2 核心技术亮点

方案兼顾稳定性、易用性与可扩展性，核心技术亮点聚焦关键痛点解决，简洁突出：

技术点 核心优势
分层架构设计 应用层、服务层、基础层职责解耦，无缝对接外部平台，提升系统扩展性。
页面状态机设计 定义页面全生命周期状态及流转规则，避免并发冲突，保障流程有序可控。
AI Agent 深度集成 串联匹配与生码核心环节，实现智能化、自动化，降低人工干预成本。
文件唯一映射机制 生码文件插入唯一 ID，建立可靠映射关系，为指标计算提供追溯依据。
多维度效能指标体系 覆盖全流程指标，结合 GitLab Webhook 实现自动计算，数据实时可追溯。

10.3 后续优化方向

围绕精度提升、功能完善、体验优化，明确后续迭代重点，简洁可行：

  1. 完善 AST 对比：优化语法树对比逻辑，提升代码相似度判断精度，适配更多场景。
  2. 补全存量页面指标：设计存量页面指标计算方案，批量同步历史数据，保障统计完整性。
  3. 丰富指标维度：新增代码质量、生成效率等指标，实现多维度效能分析。
  4. 指标可视化：搭建可视化面板，支持多条件筛选，降低数据解读成本。
  5. 优化异常处理：完善异常捕获与重试逻辑，补充错误日志，提升系统容错性。
相关推荐
浔川python社1 小时前
HTML头部元信息避坑指南技术文章大纲
前端·html
IT_陈寒1 小时前
SpringBoot配置加载顺序把我坑惨了
前端·人工智能·后端
kyriewen1 小时前
Next.js部署：从本地跑得欢，到线上飞得稳
前端·react.js·next.js
Moment2 小时前
面试官：给 llm 传递上下文，有哪几个身份 role ❓❓❓
前端·后端·面试
跨境数据猎手2 小时前
跨境独立站系统技术拆解(附带源码)
服务器·前端·php
豹哥学前端2 小时前
用猜数字游戏，一口气掌握 JavaScript 核心知识点（附完整代码）
前端·javascript
ZZH_AI项目交付2 小时前
我 Vibe Coding 了一个 iOS / Flutter 项目的 AI 代码改动检查工具
app·aigc·ai编程
忆往wu前2 小时前
从0到1一步步拆解搭建，梳理一个 Vue3 简易图书后台全开发流程
前端·javascript·vue.js
木斯佳2 小时前
前端八股文面经大全：字节抖音前端三面（2026-04-27）·面经深度解析
前端·面试·笔试·八股·面经
热门推荐
01GitHub 镜像站点02近期有什么ai的新消息，新动态？ 2026.4月03Codex 接入 DeepSeek API 完整配置文档042026年4月AI大事件深度解读：大模型竞争进入“深水区“052026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot06【AI】2026 年具身智能模型和世界模型总结07在Windows 11上安装Docker的踩坑记录08零基础教你claude code 接入 deepseek V409VSCode + Copilot下：配置并使用 DeepSeek10实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲