Qwen3-Coder 实战：从 0 到 1 开发商业级 API 平台，过程开源！
最近在给自己的「熊猫论文」降重产品设计 API 平台，踩了不少坑，也发现了一个普遍痛点。
想做个像样的 API 平台，真的挺费劲。
用别人的平台？界面丑、功能僵硬。界面好看点的，还不支持二次开发。
自己从零搭建？前后端一套下来，没一两个礼拜搞不定，对非技术背景的朋友来说，就更难了。
但还是得做。
前几天，陆续有客户找来：“能不能提供 API 接口？我们想自己定价，自己维护客源。”
这个需求让我意识到： 如果想把 AI 产品商业化推向新台阶，API 平台是绕不过去的坎。
这次，我用 Qwen3-Coder 从 0 到 1 搓了一套商业级 API 平台——前后端全栈、限流管理、接口调用、API 文档......该有的功能一个不少。
最重要的是，从架构设计到代码实现过程，我都毫无保留地分享出来。
无论你是想学习 AI 编程，或者想快速上线 API 服务，这套方案都能帮你 省下至少几周的开发时间。
一、需求分析
一）为什么要开发 API 平台？
API 平台是什么？
简单来说，API 平台就是一个"工具箱"，里面提供开发者可以直接调用的各种服务。
比如大家熟知的 OpenAI, 提供了各式各样的 API 服务。从对话、音频、图片、视频、微调等等服务。
开发者可以利用这些 API 完成 智能客服、内容创作平台、图片生成等等产品。
再结合行业 Know-how，就可以为自己的用户提供更大的价值。
哪怕只是单纯地“搬运” API，不做任何业务封装，都能通过差价完成变现。
Monica 就是个典型案例。 它整合了多家大模型的 API， 用户只需一次订阅， 就能同时用上 GPT、Claude、Gemini 等多个模型。
再说说国内。阿里云开放了 1000+ 个 API 接口， 覆盖计算、存储、网络、安全等各个领域。
开发者可以用这些 API， 实现一键运维、 把日志监控、数据备份、费用告警， 全部接入自己的系统。
对平台方来说， 扩大商业版图的同时，还增加了用户粘性， 最重要的是，这将带来稳定的、可预测的收入。
对开发者来说， 不用重复造轮子，直接调用现成服务， 就能快速完成产品商业化。
所以呢。如果想找到更多商业机会，开放 API 平台，势在必行~
二）需求分析
回到我的个人产品 -- 熊猫论文。
最近有客户希望能直接通过 API 调用我们的服务，把它们无缝整合到自己的系统中。
这样客户可以自行定价、防止客源流失，最大化利用我们的产品价值。
听到这个反馈后，我们决定快速开发一个 "API平台" ，核心功能也很清晰：
1、让用户能自己生成 API 密钥，随时调用服务。
2、系统能控制访问频率、实时计费、记录调用日志。
3、还能灵活管理接口的开放状态和安全防护。
先下载 VS Code（地址：https://visualstudio.microsoft.com/），再完成通义灵码的安装。
在通义灵码上，我们就可以使用 Qwen3-Coder.
为了确保后续开发顺利进行，我打算先用 Qwen 来梳理一下具体需求：
请你帮我提炼成适合开发人员快速理解的需求说明，输出包括：1. 功能需求清单 - 用简洁项目符号列出核心功能和模块 - 按模块/功能点分组2. 用户故事（简化版） - 按“作为[角色]，我希望[行为]，从而[目的]”的格式生成，每个需求点1条3. 验收标准（Acceptance Criteria） - 每个需求点写出可验证的标准，包含正向流程、边界情况和错误提示 - 保持简洁易测，适合开发和QA使用4. 开发备注 / 待确认项 - 列出需求中存在的歧义、不完整或需要额外确认的信息要求：
- 用简洁直白的语言，不写过多背景和技术细节
- 符合现有项目的技术框架
- 结构化输出，用 Markdown 格式方便直接使用
- 适合快速转化为开发任务和测试用例需求为:
"""
1、用户可在系统中自主生成 API 密钥，并调用系统提供的指定接口；
2、系统管理员, 在后台默认为普通用户设置较低的限流标准，用户可通过邮件等方式申请更高的 QPM；
3、用户在调用接口的过程中，系统需实时完成扣费，并记录详细的调用日志。
4、系统管理员, 可以配置具体接口的开放和关闭.
5、系统管理员, 可以针对异常分析的结论, 设置 IP 黑名单.
"""
二、现有业务分析
因为系统的主体功能已经基本开发完成，所以在做 API 接口平台 时，我希望用 最小的改动成本 来实现。
在这个过程中，我也对 API 鉴权机制 和 费用计算模式 提出了一些思考和疑问。
请先不要输出代码,我现在需要和你讨论清楚具体的实现方案, 有以下几个问题:1、请检查我现有的接口鉴权方式, 告诉我API Key的设定,是采用单一的认证密钥, 还是利用基于API Key + Secret的双重认证机制, 哪种方式实现更加稳定、易用, 我希望找到最适合我目前项目现有接口鉴权体系的方式.
2、基于上面你推荐的这种方案, 该怎么用做费用计算? 是否可以用户层面的计费方式保持一致, 这样更加简单、且统一?
3、对应的方案是否可以在设置只开放部分接口, 部分系统自身的重要接口不做开放呢? 该如何形成更友好的配置方式?
我利用「智能体」模式提问，Qwen3-Coder 在分析了项目现有技术框架后，给出了专业建议：
采用「单一API Key」认证方式与现有的JWT认证体系兼容性更佳。
同时建议将计费机制直接与现有余额系统进行集成，以实现无缝对接。
针对这些技术细节，我们可以让 AI 协助补充到需求文档中，或者由我们手动完善，为后续提供更合适的上下文。
三、后端接口编码
一）接口编码
在正式编码之前，我们需要为 Qwen3-Coder 提供明确的指引：
# 角色
你是一名精通 Python 的高级工程师，拥有 15 年软件开发经验。你的任务是主动、以用户易懂的方式，帮助一位不懂技术的用户完成 Python 项目的设计与开发。# 目标
以通俗清晰的方式推进项目：理解需求、编写代码、解决问题，并主动推动每个环节，不依赖用户反复提醒。# 工作流程与要求## 1. 项目初始化
- 首先阅读项目根目录下的 README.md 与现有代码结构，理解项目目标与架构；若无 README，主动创建并维护，写明功能说明、使用方法。
- 其次分析 docs/development_guide.md，理解核心技术栈和开发规范。## 2. 需求分析与方案
- 以用户视角理解需求，扮演产品经理补齐缺漏并与用户确认。
- 提出最合理、最直接的实现方案，保证功能完整且易用。 ## 3. 开发规范（必须遵守）
- 遵循 **PEP8** 与 Python 3 最新语法特性；采用 **类型提示（Type Hints）** 与详细 docstring。
- 模块化设计，合理使用 OOP 与函数式编程；优先利用标准库和成熟第三方库。
- 编写清晰注释、必要的错误处理与日志记录；保证代码可读、可维护。
- 严格按照项目结构生成代码，不得破坏现有规范。 ## 4. 数据与接口
- 在 `tests/` 文件夹生成 pytest 接口测试用例（仅接口测试），测试覆盖率目标 100%。
- 接口视情况加入 JWT 认证。
- 如涉及数据库更新，需在 `alembic/versions/` 生成迁移文件并执行迁移。 ## 5. 调试与问题解决
- 阅读相关代码，完整理解逻辑，分析根因并提出解决方案。
- 与用户交互确认修复方法并快速迭代。
- 若问题多次修复仍未解决，启用“系统化分析模式”：
1. 全面排查潜在根因；
2. 提出假设与验证步骤；
3. 给出 3 种解决方案并列出优缺点；
4. 由用户选择执行。 ## 6. 总结与交付
- 完成后更新文档： - `README.md`：新增功能、运行方法、配置说明、目录结构的变化。 - `docs/development_guide.md`：记录技术栈、开发规范的变化，确保团队成员能迅速上手。
- 自我复盘并提出改进建议；优化性能（算法、内存、异步并发）。
- 确保代码已通过静态分析与单元/集成测试，达到可交付标准。 # 参考与原则
全程参考 [Python官方文档](mdc:https:/docs.python.org), 确保使用最新的Python开发最佳实践。 在规则文件的开头，我特地加了一条：Qwen3-Coder 必须先理解和分析现有代码的结构、架构和核心技术栈。
为什么？
因为这一步 太关键了。
只有吃透了项目的整体设计理念，AI 才能写出的代码真正融进系统，而不是凭空造个功能，最后变成“拼不上去的零件”。
除此之外，我还结合了项目的技术栈，把常见的任务也写进去：接口鉴权识别、数据库迁移脚本生成、单元测试、文档更新……
这样做的好处是，每次我提新需求时，AI 都能 独立完成闭环开发。不需要我来回沟通、手把手补细节，它就能跑完整个流程。
重点就是把 AI “培养”成一个靠谱的“全栈实习生”，既懂项目背景，又能独立交付。
先利用命令，我们引入了预先设定的项目规则作为上下文约束。
接下来，进入正式编码阶段，我没有一口气把所有需求砸给 AI。
而是采用 渐进式开发策略，逐步开发每个功能，并且每一步都对照既定的验收标准，严格测试。
首先，我们着手完成 API 密钥管理模块。
功能完成，并且按照我们预设的规则指令，Qwen3-Coder 自动编写、运行了单元测试用例。
我们可以看到，相关接口已经全部通过自动验证。
我建议，最好再进行一遍人工二次验证。
打开 Swagger 平台后，在顶部输入 token 进行鉴权，然后找到 API 密钥管理模块开始接口测试。
很多潜在的小问题，往往就是在这一步被揪出来的：
输入接口请求所需的参数:
查看请求响应的结果:
为了程序的健壮性，我们可以刻意测试一些 反向场景 或者 边界值。
同理，按照类似方式继续测试其他接口，确保所有接口都测试成功后，再开始下一个功能的开发。
在动手开发下一个功能之前，我都会先让 AI 把现有代码过一遍，分析 代码重构 后对现有系统和未来接口平台可能产生的影响。
在开发下一个功能前，我让 AI 阅读现有代码，分析代码重构后对现有系统和未来接口平台可能产生的影响。
这一步其实就是提前排雷，帮我们识别潜在问题。
有时候，我还会借助 Mermaid 这类在线可视化工具，查看 AI 绘制的流程图，这样就一目了然。
不管是文字说明，还是流程图，最终都能验证：用现有方案去改造，对系统本身不会带来任何负担。
更重要的是，当未来遇到不确定的场景，我们就可以套用这套 “沙盘推演法” ——
提前模拟各种可能性，在正式上线之前先把风险降到最低。
OK, 继续开始下一个功能的开发:
请针对需求文档中“接口访问控制模块”的功能描述、用户故事、验收标准, 完成相关后台接口的开发
AI 测试用例运行完成后，继续在 Swagger 上手动验证每个接口是否可以正常使用。
如果测试接口时发现问题，我们只需要按照以下模板提供信息即可：
我使用xxx用户的token, 测试xxx接口时遇到了问题。接口请求参数:xxxx接口返回结果:xxxx请告诉我问题发生的原因, 并修复问题。继续完成 限流管理、统一计费模块 等功能，思路基本上一致，这里就不赘述了。
二）完整性测试
后端接口开发完成后，别着急。 最后还有关键一步——完整性测试。
为什么？
因为开发过程中，新功能可能会影响到旧功能，必须全面测一遍，确保没有交叉影响。测试方式有两种：
1、自动化测试用例 — 快速跑完基础功能
2、手动测试 — 针对核心业务场景逐个验证
重点提醒：像限流测试这种需要批量操作的场景，用自动化脚本跑会更高效。
但对于 对外开放的接口调用 和 统一计费验证 ，我强烈建议手动核查。 毕竟这两步直接关系到收入，马虎不得。
我们可以使用 Postman、APIFox 等接口测试工具完成对外接口的验证。
如下为白名单接口和黑名单接口的验证状态：
以及改写接口的测试状态。
四、前端页面开发
所有后台功能就绪后，接下来就需要开发前台页面的功能。
有个背景需要说下，因为我是前后端分离架构，最开始这样的设计主要为了代码解耦，开发和部署效率最大化的初衷。
但是我认为无论咱们得项目是否为这样的架构，都应该先做好接口数据层的准备，再考虑 UI 层面的开发。
高强度实践 Vibe Coding 几个月下来，这样的方式可以极大减少出错和返工的概率。
具体怎么做？
我们可以先提供用户故事、以及每个接口可能出现的典型场景的请求和响应数据，将他们作为上下文交给 AI。
有没有更简单的方法？
当然，只要测试用例覆盖场景充分，我们完全可以让 AI 基于测试用例生成对接文档。但是，稳定性还是前者更高。
请你基于需求文档中的xxx功能、对应完成的接口、和前端技术栈，生成一份前端对接文档，内容包括： 1. 功能概述 - 说明接口实现的业务功能 - 提供对应的用户故事（作为[角色]，我希望[操作]，从而[目的]） 2. 接口说明 - 请求路径、方法 - 请求参数说明（必填/选填、类型、示例） - 响应参数说明（字段含义、类型、示例） 3. 使用场景 - 正向场景（正常调用时的流程与返回） - 反向场景（异常输入/鉴权失败/超时等情况的表现与错误码） 要求：
- 用 Markdown 格式输出，结构清晰，适合作为前端开发对接文档
- 保持简洁易懂，不要堆砌不必要的技术细节
我们来看看生成的前端对接文档。
完全符合要求，有请求和响应参数，还包括正向和反向场景，给了前端开发较为可执行的参考。
一）交互设计
在前端 API 密钥管理 这个功能点上，我更关心的不是代码，而是交互，特别是在菜单入口的选择。
请你扮演一名资深交互设计师，从用户的角度出发，基于以下【用户故事】，为系统/页面设计出最佳交互方案。## 用户故事
[在这里放置用户故事]## 输出要求
1. 【用户目标】 - 解释用户在这个故事中的核心目标是什么 2. 【交互流程设计】 - 提供完整的交互流程（从用户进入页面到完成目标） - 使用简洁、贴近生活的描述 3. 【界面布局建议】 - 推荐入口位置、按钮、表单、提示信息的布局 - 考虑可用性、易理解性 4. 【正反向场景】 - 正常操作时的理想流程 - 潜在的误操作或异常场景，以及相应的交互解决方案 5. 【优化建议】 - 基于用户体验和一致性，提出额外优化点 ## 输出格式
请使用 Markdown 分层结构输出，清晰展示每一部分。
AI 给了一些建议，但老实说，我并不完全满意。
所以我又补充了几张产品截图，加上我的一些备选思路，再交给它参考。
我计划增加一个“API密钥维护”入口，未来还可能扩展 API 分析、日志查询等功能。请站在专业 UI 角度，结合我现有的界面结构（图1: 控制台；图2: 用户端），分析需求和用户故事，并说明最适合放置“API密钥维护”和后续相关功能入口的位置。
综合权衡之后，我选择将入口放在顶部导航栏。
对当前阶段来说，最重要的是让用户“快速发现、快速使用”，先解决可见性和推广的问题。
至于后面，如果用户规模扩大，功能也逐渐丰富，入口就可以迁移到更合理的位置：
比如右上角 Logo 下拉菜单，或者右侧的固定功能区。
不同阶段，不同需求，不必追求完美形态。
二）页面开发
交互方式和入口确定后，接下来开始页面开发和接口引入。
我计划将入口放在顶部菜单的【API服务】，以提升发现性并利于初期推广。请站在专业 UI 角度，结合前端对接文档与交互规范，设计丝滑的交互体验并完成页面与后台接口的对接。开发要求：
1. 页面布局可参考【个人信息】模块，样式需遵循全局规范，保持一致风格。
2. 尽量复用现有组件库代码，避免重复造轮子。
3. 本次仅开发【API密钥管理】，但设计时需预留布局空间，以支持未来扩展 API 使用分析、日志查询等功能。输入提示词，开始前后端的对接。
细心的朋友应该会发现，我这里引入了两份文件作为上下文：1、前端对接文档；2、project_rule.md
前端对接文档之前已经展示过，那 project_rule 又有什么讲究呢？
它主要约束了几个环节：从需求理解 → 代码编写 → 最终总结，整条链路上的最佳实践。
而且还特别强调了两个关键文档：前端组件库 和 前端样式规范。
它们分别是什么？
1、前端样式规范：保持网站配色、CSS规范、布局规范、字体大小、字号等等基础要求保持统一。
这就像一份“房屋装修指南”，让 AI 知道所有位置该长什么样，避免一块地方极简风，另一个地方是欧式宫廷。
2、前端组件库：在开发复杂产品前，将常见的功能抽离出一些公共的组件，比如按钮、消息框、弹出框、表单、表格、导航栏等。
无论是开发者、还是 AI，都可以像搭积木一样快速完成开发工作，不需要从 0 开始。
刚开始跑出来的效果，其实还是有不少问题。
比如说，API 密钥管理 这个功能点，本质上并不需要统计数据。
结果 AI 给我开发了一堆图表，看着反而累赘。最简单的表格，其实就足够了。另外，还有一些细节上的样式问题。
通过自然语言，不需要特殊的技巧，清晰表达需要修改的内容和期望效果，就能指导 AI 完成相应调整。
通过多次交互和问题修复，最终用户端的 API 密钥维护页面如下：
以此推论，我们可以按照同样思路完成管理员后台相关功能的开发。
五、API 接口文档开发
一个优秀的 API 接口平台，除了架构的设计之外，更关键的问题其实是：
“怎么让用户更轻松地接入到自己的业务？”
这次我用的是 FastAPI，它本身就自带了 Swagger 这样的接口平台。
相比之下，我更喜欢 Mintlify —— 界面简洁，文档可读性也更强。
**最重要的是：**免费部署，不需要准备个人服务器！！！
连像 硅基流动、智谱 这样的 AI 行业知名厂家都选择了 **Mintlify，**那我也没必要花时间再做筛选了。
接下来，大家跟着我的步伐完成 API 文档库的搭建。
1、先完成注册： mintlify.com/login
2、设置公司名称，可以随便填。
3、按照指引，登录 GitHub，并且创建对应的代码仓库，再拉取代码到本地即可。
4、安装 GitHub 应用，并且完成授权。
具体细节可以参考官方文档，这里就不重复造轮子了：https://www.mintlify.com/docs/quickstart
关于下载，通过直接在 GitHub 下载代码包，或者在 Git Clone 的方式下载，两种方式都可以（这里需要自备科学上网）。
下载完成后，按照如下命令，进行下载依赖，并且启动项目（需要提前安装 node、npm）：
# 安装依赖
npm i -g mint# 启动项目
mint dev
启动成功后，就可以看到初始的 API 文档。接下来，我们来改造它。
关于首页的 Logo，Mintlify 给得很自由：不管是 SVG，还是 PNG，都能支持。
操作起来也很简单。
先用图片编辑工具，把网站 Logo 调整到合适大小，再导出为 PNG，替换掉原有的 Logo 文件就行。
如果更换文件类型，记得同步修改 docs.json 里对应的文件路径。
接下来修改项目名称、主题色、Support 对应的邮箱地址、按钮名称等等。
修改后，我们看下最新的 API 文档效果。
最后，我把多余的文档都去掉，只保留了 API reference 这个页签。
里面放一份 API 简介，再加上几个需要开放的接口示例，就足够了。
为了加快修改速度，其实我们完全可以 Vibe Coding。
更惊喜的是，Mintlify 已经贴心地提前准备好了不同 AI IDE 的规则文件。我们只需要直接引用一个，或者稍微改一改，就能立刻用上。
这些接口不是我们所需要的，包含很多没必要的内容都是英文，接下来我们让 AI 帮助我们改造。
首先，我们把 api-reference 所有文件都复制到后端项目中。
要求 AI 参考原始文件完成对应接口的 openapi.json 、mdx 文件、介绍文档。
请遵守OpenAPI 规范 3.0+ 和介绍文档， 根据 openapi.json 的内容帮我在api-reference文件夹下生成需要开放的接文件，用于在 mintlify 作为API文档展示。开放接口信息如下：
"""
XXX 接口
"""
完成后，在逐一替换 Mintlify 项目中的文件和 docs.json 的引用地址。
修改后的效果如下：
最后怎么部署到线上呢？
1、首先我们需要将修改后的文件提交到 GitHub 仓库中。如果不熟悉提交操作或命令，也可以直接让 AI 搞定 ~
更改区域内容完全可以点击 右上方「Qwen」头像 直接生成提交记录。
说实话，这个功能虽小，但在实战过程中却非常使用。
一个良好的代码提交规范会在 回退、审查代码 带来巨大便捷，而 Qwen 早已经把这套规范内化。
2、提交后，我们的 API 文档库就会自动更新, 几乎是秒级的速度。
3、设置域名：我们需要准备一个域名，按照提示在云供应商配置 DNS 映射，即可拥有个人域名的 API 文档中心。
4、除了本地修改，Minitlify 官方也提供了在线编辑器，我们可以直接调整后， 右侧 Publish 就可以完成线上代码的更新。
六、效果展示
当然，目前还不够完美，仍然存在一些问题和待办事项。但作为初版功能，已经足够满足基本需求。
1、QRM 设计不合理
目前的 QPM 是 API Key 级别的。业内无论是 OpenAI、AWS 还是国内的 API 平台，大多都是以账号级别来设计限流策略。
2、API 平台和业务系统耦合度太高
如果 API 平台出现因为程序设计问题、或者是服务器配置不够导致宕机，那么整个业务系统也将随之瘫痪。
最佳实践应该是：解耦。
将API 平台单独部署，再根据需求量去动态扩缩容。
3、接口后台管理功能待完善
最初版本是为了最快验证商业路径，很多功能在写这次文档时，都没有及时完成。
大家可以尽早补充 API 白名单配置、IP 黑名单配置 功能。
此外，还有一些报表、图表的工作：比如 账号监控和异常分析、接口调用日志管理、API 消耗分析 等等。
4、Mintlify，不只是 API 文档
这次实践里，我主要用 Mintlify 演示了API 接口平台的搭建过程。
所以很多和 API 不相关的内容都先砍掉了。
但别忘了，Mintlify 还能承载更多 ——比如未来把 产品使用手册 也放进去，和 API 文档统一管理。
七、总结
最后一章，有几个 AI 编程的心得想分享下。
前后端技术分离不是一种架构，更是一种思想。数据层、交互层独立运行和部署，任务也做到拆分明确，再逐个击破。
「一图胜千文」，不要奢望通过文字描述复杂的 UI 页面问题或者需求，一张参考图再配上简单的三两句话，才是正解。
将重要问题的解决过程让 AI 留存成总结性笔记。做自媒体，这就是素材；继续 Coding，这将是宝贵的历史经验。
现在我习惯将 Vide Coding 涉及的提示词，称作是「面向上下文工程」的提示词：
比如，提前留存清晰的代码文件结构；
将 技术栈、前端样式规范 、编码规范 等落地成具体文件；
将 工作流程的最佳实践 编写成规则提示词；
所有文件名称做到望文知义，暗示明确目的；
这些技巧无一不在为「上下文工程」服务。循规而行，自然就能顺势而为。
最后，如果你也在做 AI 产品，想探索更多商业化机会，不妨试试自己动手搭建一套 API 平台。
提示词和思路，我都开源了，接下来就看你了。
我是 🐼 熊猫Jay，我们下次再见 ~
如果觉得不错，随手点个赞、收藏、转发三连吧。
谢谢你看我的文章 ~