从零到一：用 CodeArts + Flask 构建菜谱小工具的实战之旅

作者：Eddygit
日期：2026-09-26
标签：Flask, Bootstrap 5, CodeArts, Web开发, IaC

写在前面

这篇文章记录了我使用华为云 CodeArts Agent 辅助开发一个菜谱小工具的完整过程。从需求构思到代码生成、从本地部署到发布上架，每一步都走得扎实。这不是一篇教程，而是一次真实的开发日志——包括踩过的坑、做出的取舍、以及对未来优化的思考。

一、技术路线选型

1.1 为什么选 Flask？

在开始之前，我面临一个经典选择：Flask 还是 Django？

对于这个菜谱小工具来说，需求很明确：

• 4 个路由（首页、详情页、API、搜索）
• 12 条内置数据
• 无需数据库、无需用户系统、无需 Admin 后台

Django 的 ORM、Admin、Form 组件在这个场景下全是多余的重量。Flask 的"微框架"哲学恰好匹配——一个 app.py 文件搞定所有逻辑，requirements.txt 只有一行 flask。

选型的核心原则：不要为了"可能用到"而引入当前不需要的复杂度。

1.2 前端为什么用 Bootstrap 5 而不是 Vue/React？

这是一个工具类小项目，核心目标是"能用、好看"。Bootstrap 5 通过 CDN 引入，零构建工具链：

• 栅格系统解决响应式布局
• 卡片组件直接套用
• Offcanvas 组件实现移动端筛选面板
• 徽章组件展示难度等级

引入 Vue/React 意味着需要 Node.js、构建工具、状态管理——这些对于一个 12 道菜谱的展示页面来说，是典型的过度工程。

1.3 收藏功能为什么用 localStorage？

收藏功能是这个工具唯一的"状态"需求。选择 localStorage 的理由：

• 零后端依赖：不需要数据库、不需要用户登录
• 即时响应：JavaScript 直接读写，无网络延迟
• 持久化：浏览器关闭后数据仍在

代价是：换设备/浏览器后收藏会丢失。但对于一个工具类 demo，这个代价完全可以接受。

二、开发实战过程

2.1 CodeArts Agent 辅助开发

这次开发我使用了华为云 CodeArts Agent（基于 ACP 协议的 AI 编码助手）。整个流程：

1. 描述需求：用自然语言描述要做什么——“创建一个菜谱小工具 Web 应用，Flask + Bootstrap 5，支持浏览/搜索/收藏”
2. Agent 自动生成：CodeArts 自动创建项目结构、编写代码、安装依赖、启动服务
3. 验证：Agent 自动验证首页、详情页、API、静态资源均返回 200

关键观察：

• CodeArts 会先检查环境（Python 版本、端口占用），再开始生成代码
• 生成的代码质量不错——有防抖搜索、分类筛选、toast 提示等细节
• 自动安装依赖并启动服务，无需手动操作

2.2 项目结构设计

最终的项目结构：

recipe-tool/
├── app.py                  # Flask 主应用
├── requirements.txt        # 依赖
├── templates/
│   ├── index.html          # 首页
│   └── recipe.html         # 详情页
└── static/
    ├── css/style.css       # 样式
    └── js/main.js          # 逻辑

这是一个经典的 Flask 项目结构。templates/ 放 Jinja2 模板，static/ 放静态资源。没有多余的目录，没有过度分层。

2.3 路由设计

GET /                    → 首页（渲染菜谱列表）
GET /recipe/<int:id>     → 详情页（渲染单道菜谱）
GET /api/recipes         → JSON API（全部菜谱）
GET /api/search?q=xxx    → JSON API（搜索菜谱）

前两个是页面路由，后两个是 API 路由。前端 JavaScript 通过 fetch 调用 API 实现动态筛选和搜索，页面不刷新。

2.4 数据模型

每道菜谱的数据结构：

{
    "id": 1,
    "name": "宫保鸡丁",
    "category": "川菜",
    "difficulty": "中等",
    "cook_time": "30分钟",
    "description": "经典川菜，花生与鸡丁的完美搭配",
    "image": "https://placehold.co/600x400?text=宫保鸡丁",
    "ingredients": ["鸡胸肉 300g", "花生米 50g", "干辣椒 10g", ...],
    "steps": ["鸡肉切丁腌制", "花生米炒香", "热锅下油爆香辣椒", ...]
}

这个结构简单直接——ingredients 是列表，steps 是有序列表，前端渲染时分别用不同的样式呈现。

三、技术心得

3.1 前端筛选 vs 后端筛选

12 条数据做筛选，放在前端还是后端？

我选择了前端筛选。原因：

• 数据量小（12 条），前端遍历几乎无延迟
• 减少 HTTP 请求，用户体验更流畅
• 搜索带 300ms 防抖，避免频繁重渲染

如果数据量增长到数百条以上，就需要改为后端筛选 + 分页了。这是一个典型的"数据量决定架构"的例子。

3.2 难度标签的颜色设计

三档难度用三种颜色区分：

• 简单 → 绿色（success）
• 中等 → 黄色（warning）
• 困难 → 红色（danger）

这不是随便选的——绿色暗示"放心做"，黄色暗示"有点挑战"，红色暗示"需要经验"。颜色本身在传递信息，而不只是装饰。

3.3 移动端适配

移动端的筛选面板用了 Bootstrap 的 Offcanvas 组件——从侧边滑出，不遮挡内容。这比传统的下拉菜单更友好，因为菜系分类有 7 个选项，下拉菜单会很长。

四、发布到开发者作品展览馆

4.1 发布流程

使用 huawei-cloud-publish-work-to-gallery skill 完成发布，流程包括：

1. 扫描项目 → 识别 recipe-tool 项目
2. 解析 IAM Domain ID → 通过 hcloud CLI 获取华为云账号信息
3. 生成 STS 临时凭证 → 创建自委托 SELF_VERIFY，获取 900s 有效期的临时凭证
4. Git 仓库信息 → 读取 gitUrl 和 gitBranch
5. 封面图生成 → 用 Playwright 截图 + 合成 polaroid 布局封面
6. 简介生成 → 从 README 提取，控制在 15-50 字符
7. 详情包打包 → README + 架构图打包成 zip
8. 选择训练营 → 选择"布道师通用产品体验"
9. 发布 → API 调用，返回 workId 和作品链接

4.2 踩坑记录

坑1：端口冲突
CodeArts 沙箱中的 Flask 进程占用了 5000 端口，从工作区启动时冲突。解决方案：终止沙箱进程后重启。

坑2：字体安装慢
Preflight 检查需要安装 CJK 字体（用于截图），默认 yum 源太慢。解决方案：设置 YUM_MIRROR_BASEURL=https://mirrors.huaweicloud.com/openeuler 走华为云镜像。

坑3：作品名中的 emoji
README 的 H1 标题包含 emoji（🍳），提取出的作品名带 emoji 可能导致问题。解决方案：发布时使用简化的"菜谱小工具"作为作品名。

五、存在问题与优化空间

5.1 当前局限

5.2 优化路线图

短期（1-2周）：

• 接入 SQLite 数据库，菜谱数据从代码迁移到数据库
• 接入真实菜谱图片（OBS 对象存储）
• 扩充菜谱数据至 50+ 道

中期（1-2月）：

• 增加用户注册登录系统
• 收藏功能改为服务端存储
• 支持用户上传自己的菜谱

长期（3-6月）：

• 根据食材自动计算热量和营养成分
• 基于用户偏好的智能推荐
• 接入 AI 辅助生成菜谱步骤

5.3 架构演进思考

当前架构是典型的单体 Flask 应用。如果菜谱数据增长到数千条、用户量上来后，需要考虑：

• 前后端分离：Flask 只做 API，前端用 Vue/React
• 数据库迁移：SQLite → MySQL/PostgreSQL
• 缓存层：Redis 缓存热门菜谱查询
• CDN 加速：静态资源和图片走 CDN

但这些是"当需要时再做"的事情。当前阶段，一个能跑、好看、有用的菜谱小工具，已经达到了它的目标。

六、总结

这次开发实践让我体会到几点：

1. 技术选型要匹配场景：Flask + Bootstrap 5 对于这个规模的项目是最佳选择，不需要更重的框架
2. AI 辅助开发提效明显：CodeArts Agent 从需求描述到可运行的服务，全程自动化，节省了大量重复性工作
3. 发布流程可以标准化：通过 skill 封装发布流程，从 STS 凭证到封面生成到 API 发布，全链路自动化
4. 简单不等于简陋：12 道菜谱、4 个路由、1 个 localStorage——简单的技术栈也能做出好用的工具

最好的架构不是最先进的架构，而是最适合当前场景的架构。当你只有 12 道菜谱时，一个 app.py 就够了。

本文为原创技术分享，转载请注明出处。