一份写给前端开发者的 Python 小项目实战指南# 实战搭建 AI Code Review 自动化流水线# GitLab-Runner AI 代码审查服务 远程大模型 全套部署运维实战缘起为什么我要写这份笔记前几天我搭了一套 AI 代码审查服务用 Python Flask 写了大概 200 行代码实现了当 GitLab 收到 MR 时自动调用 AI 分析代码 diff然后把审查意见贴回 MR 评论区。团队里几个前端同事看了都很好奇“我不会 Python这个能学会吗” 我就想干脆写一份零基础也能看懂的学习笔记把我踩过的坑、理解的过程都记录下来。一、这个服务到底干了什么事你先别管代码我们先理清楚它想解决什么问题每次有人提 MR都要人工 review很慢而且有些低级错误比如忘记处理空值、变量命名不规范反复出现。我们希望让 AI 先帮忙扫一遍把明显的错误挑出来人工只需要看复杂逻辑。所以这个服务的流程就是GitLab CI 触发一个任务 →调用这个 Python 服务传过去项目名、MR 编号→Python 服务从 GitLab 拉取这次 MR 的代码变更diff→把 diff 发给大模型比如 GPT-4→大模型按我们的规范返回审查意见 →服务再把这些意见通过 GitLab API 贴到 MR 评论区。你可以把它想象成一个会看代码的 AI 同事24 小时在线随叫随到。二、这个项目用了哪些技术尽量让前端看懂技术作用类比前端视角Python 3后端语言类似 Node.jsFlaskWeb 框架类似 ExpressOpenAI SDK调用大模型类似调用第三方 APIrequests发 HTTP 请求类似 axiospython-dotenv读取.env配置类似dotenv包git 命令克隆规范文件仓库就是git clone所以即使你不会 Python只要你会写 JavaScript理解这些概念都不难——只是语法不同罢了。三、手把手运行起来Mac / Linux1. 安装 Python如果没有Mac 用户一般电脑自带brewinstallpython3验证python3--version# 应该显示 3.9 以上2. 下载代码把上面那份app.py保存到一个文件夹里比如~/ai-review-service/。同时创建一个requirements.txt内容如下flask openai python-dotenv requests3. 安装依赖cd~/ai-review-service pip3install-rrequirements.txt如果提示pip3找不到试试pip。或者用python3 -m pip install ...4. 配置环境变量创建.env文件在相同目录下新建.env文件内容如下把尖括号里的换成你自己的OPENAI_API_KEYsk-xxxxxxxxxxxxxx OPENAI_BASE_URLhttps://api.openai.com/v1 OPENAI_MODELgpt-4o-mini GITLAB_TOKENglpat-xxxxxxxxxxxx GITLAB_URLhttps://gitlab.com REVIEW_SPEC_PATH./specs/frontend-code-review.md AUTO_SYNC_SPECtrue SKILLS_REPO_URLhttps://gitlab.com/your-team/skills.git各字段含义我后面会详细解释。5. 启动服务python3 app.py看到类似下面的输出就成功了 AI Review 服务启动中... 服务地址: http://localhost:5001 测试令牌: test-token-123 审查接口: POST /api/review四、配置文件.env详解小白必看变量含义从哪里获取OPENAI_API_KEY调用 OpenAI或兼容接口的密钥在 OpenAI 官网或阿里云 DashScope 申请OPENAI_BASE_URLAPI 地址默认是 OpenAI 官方如果国内用通义千问就改成阿里云地址OPENAI_MODEL使用的模型名比如gpt-4o-mini、qwen3.7-maxGITLAB_TOKENGitLab 个人访问令牌GitLab → Settings → Access Tokens勾选api或read_api权限GITLAB_URL你的 GitLab 服务器地址公司内部的 GitLab 地址比如https://gitlab.your-company.comREVIEW_SPEC_PATH代码审查规范文件存放路径可以默认会在启动时从 skills 仓库下载AUTO_SYNC_SPEC是否自动同步规范true或false建议trueSKILLS_REPO_URL存放审查规范的 Git 仓库地址你自己建一个仓库里面放frontend-code-review/SKILL.md特别注意GITLAB_TOKEN必须有api权限否则无法在 MR 下发评论。如果只是测试可以先不配置GITLAB_TOKEN服务会返回“无法获取 diff”的提示但不会报错。五、代码逐段解析不要求你懂 Python但知道它在干嘛我会把app.py拆成几个核心功能用大白话解释。1. 导入依赖和读取配置fromflaskimportFlask,request,jsonifyimportosimportsubprocess# ... 其他导入load_dotenv()# 自动读取 .env 文件Flask就像 Express 的app对象用来定义路由。load_dotenv()让你能在代码里用os.getenv(OPENAI_API_KEY)拿到配置。2. 同步审查规范文件defsync_specs_from_git():# 用 git clone 拉取一个仓库然后把里面的 SKILL.md 复制到本地为什么需要这个团队代码规范可能会更新。我们把它单独放在一个 Git 仓库里服务启动时自动拉取最新版。这样不用改代码只改规范文件AI 就会按新规则审查。对前端的类比就像你npm install一个依赖包只不过这里git clone了一个文档。3. 从 GitLab 获取 MR 的 diffdefget_mr_diff(project_path,mr_iid):# 调用 GitLab API: GET /projects/:id/merge_requests/:iid/changes# 返回一个包含代码增删内容的字符串核心逻辑project_path类似group/project。mr_iid是 MR 的编号比如!123中的 123。用requests库发 GET 请求带上PRIVATE-TOKEN头。解析返回的 JSON提取changes数组中的diff字段。如果失败怎么办代码里做了详细的错误提示比如 401 告诉你 token 权限不够403 告诉你没权限访问项目。4. 调用 AI 进行审查defget_real_ai_review(mr_info,code_diff):# 1. 加载团队规范文件内容# 2. 拼接一个超长的 prompt提示词# 3. 调用 OpenAI API# 4. 解析返回的 JSON这是最核心的函数。它做的事情可以理解为给 AI 下指令。指令内容大致是你是一位审查专家。下面是 MR 的代码变更请按以下规范检查…… 输出格式必须是 JSON每个问题要标明文件、行号、优先级、分类。AI 返回的 JSON 结构类似{score:75,suggestions:[{type:error,file:src/App.vue,line:12,message:空指针风险建议加 ?.}]}前端同学注意这个 prompt 就是你的“需求文档”你想让 AI 怎么审查完全可以通过修改 prompt 来控制。甚至你可以把 ESLint 规则翻译成自然语言写进去。5. 定义 HTTP 接口路由app.route(/api/review,methods[POST])defreview_code():# 1. 验证 Authorization 头里的 Bearer token# 2. 解析请求 bodyJSON# 3. 调用 get_mr_diff 拉取代码# 4. 调用 get_real_ai_review# 5. 返回结果app.route类似 Express 的app.post()。函数名随便起但里面逻辑一定要清晰。返回的 JSON 会通过jsonify自动转成响应。6. 健康检查与测试接口app.route(/health)defhealth_check():return{status:ok,...}作用让你确认服务是否还活着以及配置是否正确比如检查 API Key 是否存在。还有一个/test/gitlab接口可以手动测试 GitLab token 是否有效。六、如何在 GitLab CI 里调用这个服务在你的前端项目根目录修改.gitlab-ci.yml添加一个 jobai-review:stage:reviewtags:-mac-runner# 如果你用本地 runnerscript:-|curl -X POST http://localhost:5001/api/review \ -H Authorization: Bearer test-token-123 \ -H Content-Type: application/json \ -d { \project\: \$CI_PROJECT_PATH\, \mr_iid\: $CI_MERGE_REQUEST_IID, \source_branch\: \$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME\, \target_branch\: \$CI_MERGE_REQUEST_TARGET_BRANCH_NAME\ }rules:-if:$CI_PIPELINE_SOURCE merge_request_event$CI_PROJECT_PATH等变量是 GitLab CI 自带的不用你手动填。test-token-123是服务里硬编码的测试 token你可以改成更安全的随机字符串。如果你不想用本地 runner也可以把这个服务部署到一台有公网 IP 的服务器上然后把http://localhost:5001换成对应的 IP。七、踩坑记录我摔过的地方1. Token 权限不足 → 401错误获取 MR 变更失败: 401原因GitLab Token 只给了read_user没给api。解决重新生成 Token权限勾选api或至少read_apiwrite_repository。2. 本地服务跑在 5001GitLab Runner 却访问不通错误curl: (7) Failed to connect to localhost port 5001原因Runner 如果是 Docker 模式localhost指向容器内部不是你的 Mac。解决要么用host.docker.internalMac要么改用 shell executor我上面用的就是 shell。3. Python 依赖安装失败错误No module named flask原因你可能用了系统自带的 Python 2.7或者忘记激活虚拟环境。解决用python3 -m pip install或者先python3 -m venv venv创建虚拟环境。4. AI 返回的 JSON 解析失败现象服务日志提示JSON 解析失败MR 里出现 raw_response。原因大模型偶尔会返回带解释文字的 JSON或者 JSON 不完整。解决代码里已经做了“尝试提取 json 代码块”的逻辑如果还失败可以让模型 temperature 更低比如 0.1。八、扩展想法你可以自己加的功能支持更多 Git 平台比如 GitHub、Gitee原理一样只是 API 地址和 Token 不同。支持本地模型用 Ollama 跑一个开源的 CodeLlama不用花 API 钱。增量审查只审查变更的部分而不是全量 diff提高速度。自动修复让 AI 不仅发现问题还生成一个修复 patch用户点一下就能应用。九、最后想说的话之前作为一个前端我一开始也觉得 Python 很陌生。但实际写下来发现Flask 比 Express 还简单不需要配置中间件不需要处理路由参数解析甚至不需要async/await默认就是同步很适合这种小工具。而且这种“小 AI 服务”的写法非常固定接收请求 → 调第三方 API → 加工数据 → 返回 JSON。你只要会写 JavaScript换成 Python 只是字典和列表的语法区别。希望这份笔记能让你有信心去改一改上面的代码甚至自己写一个。如果你在尝试中遇到问题欢迎在评论区留言或者提 issue我会把新的踩坑经历补充进来。最后再啰嗦一句代码不重要解决问题的方法才重要。这个服务虽然只有 200 行但它让团队的代码规范真正落地了这才是最有价值的部分。