企业官网建设流程全解析

• 文档
• 教程

菜谱本质上就是一套"烹饪算法"——它和程序一样，是由一系列命令式步骤组成的、按顺序执行即可得到结果（一道美味佳肴）的操作规程。本指南以开源仓库 app-ideas 中的 Recipe App 规格文档 为骨架，面向入门级（Tier-1 Beginner）开发者，讲解如何从零构建一个菜谱管理应用。读完本文，你将掌握 JSON 数据建模、DOM 列表渲染与卡片替换交互、基于 TheMealDB 开放 API 的菜谱搜索，以及"搜索→保存到本地"的完整实战链路。

项目定位：为什么把菜谱做成一个应用

app-ideas 仓库将全部项目按开发者经验分为三个层级，其中 Tier-1 面向"处于学习早期、专注构建用户界面应用"的开发者（见 README.md 的分层说明），Recipe App 正属于这一层。它的定位非常克制：

• 核心洞察：菜谱不过是"烹饪算法"，这与编程中的"命令式步骤"异曲同工——只要按步骤执行，就能得到确定的结果；
• 应用目标：帮助用户以"易于跟随"的方式管理菜谱，即把零散的菜谱组织成可浏览、可查阅、可扩展的结构化信息；
• 学习价值：规模小而完整，覆盖了数据建模、列表交互、状态切换和外部 API 集成等前端开发的核心基本功，同时预留了足够的扩展空间。

规格文档中明确给出了两条范围约束，这是开发时首先要遵守的边界：

• 初始版本允许将菜谱数据编码为JSON 文件（最简单、零依赖的数据方案）；
• 完成初始版本后，可以进一步扩展为将菜谱维护在文件或数据库中（对应升级路线）。

也就是说，第一版不引入后端，专注把"JSON 数据 → 界面展示 → 用户交互"这条链路做扎实，这正好符合 Tier-1 的训练目标。

需求规格：用户故事与验收标准

Recipe App 的需求由三条用户故事构成，它们是应用功能的最小完备集：

1. 用户可以看到菜谱标题列表；
2. 用户点击某个菜谱标题后，显示一张菜谱卡片，卡片包含：菜谱标题、餐型（breakfast 早餐 / lunch 午餐 / supper 晚餐 / snack 零食）、供餐人数、难度等级（beginner 入门 / intermediate 中级 / advanced 高级）、配料清单（含各自用量）以及准备步骤；
3. 用户点击新的菜谱标题时，当前卡片被替换为新菜谱。

第 2 条用户故事实际上定义了一个"菜谱"的完整数据契约：餐型、人数、难度、配料（带用量）、步骤。第 3 条则明确了交互模型——任何时候界面中只存在一张"当前选中"的菜谱卡片，这是整个应用状态管理的核心约束。

数据模型设计：为菜谱建立 JSON Schema

根据规格中的约束（数据编码为 JSON 文件），实现的第一步是设计数据模型。菜谱卡片需要展示的每个字段都应映射到 JSON 结构中。下面是一个建议的 schema 示例（文件可命名为recipes.json）：

{ "recipes": [ { "id": 1, "title": "番茄炒蛋", "mealType": "lunch", "servings": 2, "difficulty": "beginner", "photo": "images/tomato-egg.jpg", "ingredients": [ { "name": "番茄", "amount": "2 个" }, { "name": "鸡蛋", "amount": "3 枚" }, { "name": "食用油", "amount": "适量" }, { "name": "盐", "amount": "少许" } ], "steps": [ "番茄切块，鸡蛋打散备用", "热锅下油，先炒鸡蛋至凝固盛出", "下番茄翻炒出汁，倒入鸡蛋拌匀", "加盐调味后出锅" ] } ] }

字段语义与取值建议（与规格文档中的枚举一一对应）：

这样的结构让"卡片渲染"成为一次纯数据映射：遍历ingredients生成配料清单，遍历steps生成编号步骤，其余字段直接插值到对应位置。

核心交互实现：列表、卡片与"替换"状态

三条用户故事对应的实现要点如下：

1. 加载并渲染标题列表。将recipes.json作为静态资源引入（或通过fetch在应用启动时读取），遍历recipes数组生成可点击的标题列表。注意把"数据获取"与"界面渲染"分开：先维护一个recipes数组，再编写一个renderList()函数负责把数组渲染成 DOM 节点。

2. 渲染"当前选中"的菜谱卡片。维护一个currentRecipe状态（初始可以为null或列表第一项），当用户点击标题时更新它，然后调用renderCard(currentRecipe)渲染卡片。卡片区域应包含规格要求的全部字段：标题、餐型、人数、难度、配料表、步骤列表。

3. 点击新标题替换旧卡片。这是对"单一选中态"的自然实现：由于始终只有一个currentRecipe，点击新标题只需更新该状态并重新渲染卡片，旧卡片的内容自然被覆盖，无需处理多个卡片并存带来的复杂度。从状态管理角度看，这本质上是"受控的单选列表"模式，也是理解更复杂前端框架状态流的好起点。

一个值得注意的实现细节：餐型和难度在展示时建议做一次枚举到文案/样式的映射（如difficulty: "beginner"显示为"入门"并配上不同颜色徽标），这能让卡片信息更易读，同时保证数据层与展示层解耦。

界面布局建议

参考规格中"列表 + 卡片"的交互模型，经典的布局方案是左侧列表、右侧卡片主区：

• 左侧：纵向排列的菜谱标题列表，当前选中的标题高亮；
• 右侧：菜谱卡片，包含完整字段信息与（可选的）成品照片；
• 交互：点击左侧任意标题，右侧卡片随之切换。

布局不限定技术栈——原生 HTML/CSS/JavaScript 即可完成，也可以作为初次尝试 Vue/React 的练手项目（规格文档的示例项目中就包含 React 实现）。要点是保持"列表"与"卡片"两个区域的职责单一。

进阶功能：搜索、照片与保存

规格文档列出了六条可选的进阶功能，它们不是并列的装饰，而是一条完整的功能演进路径：

1. 成品照片

在数据模型中增加photo字段（已在上述 schema 中预留），卡片渲染时通过<img>展示成品效果图。图片缺失时应给出占位处理，避免出现破图。

2. 基于外部 API 的菜谱搜索

规格明确说明：用户可以在搜索框中输入餐名、点击Search按钮，搜索不在本地列表中的菜谱；任何开源菜谱 API 均可作为数据源，并点名推荐TheMealDB。这一点在仓库的姊妹项目 Random Meal Generator 中也被用作数据源——两个项目可共用同一套 API 接入经验。

实现上建议先用浏览器内置的Fetch API（规格文档资源列表中列出的Using Fetch指南）发起请求：

async function searchRecipes(query) { const response = await fetch(`https://www.themealdb.com/api/json/v1/1/search.php?s=${encodeURIComponent(query)}`); if (!response.ok) { throw new Error(`搜索失败：HTTP ${response.status}`); } return response.json(); }

如果偏好更简洁的 Promise 风格，也可以使用Axios库（规格文档同样列出了它）。两种方式的核心一致：向 API 发起带查询参数的 GET 请求 → 解析 JSON → 映射到菜谱卡片所需的字段。

3. 搜索结果列表与卡片查看

搜索返回后，应展示匹配的菜谱列表（而非直接只显示一条），用户点击列表中的菜谱名称即可显示其菜谱卡片——这复用了 MVP 阶段的"列表 + 卡片"交互模式，只是数据源从本地 JSON 换成了 API 返回结果。

4. 无匹配结果的警告

当 API 返回空结果时，界面应给出明确的警告信息（如"未找到匹配的菜谱"），而不是静默地显示空白页面。这是错误处理与用户体验的基本功，也是规格对健壮性的明确要求。

5. Save：把 API 菜谱收藏到本地

规格要求：对于通过 API 找到的菜谱，卡片上提供Save按钮，将副本保存到应用自己的菜谱文件或数据库中。这一条是"从外部数据到本地数据"的闭环，实现时需要注意：

• 浏览器出于安全沙箱限制，无法直接写入任意本地文件；
• 可行方案包括：生成 JSON 文件供用户下载、使用浏览器localStorage/IndexedDB持久化、或引入简单的后端接口写入数据库；
• 数据落地前需要做字段映射与清洗，把 API 返回的字段规整为本地 schema 结构（与上述 JSON 模型对齐）。

值得参考的是，仓库中同为 Tier-1 的 Weather App 展示了用localStorage持久化用户状态的模式——其"关闭浏览器后恢复上次城市并自动请求更新"的思路，可以迁移到"保存菜谱"的场景中。

开发路线与验收清单

建议按以下阶段推进，每个阶段都有明确的可验证产出：

1. 阶段一（MVP）：完成 JSON 数据文件 → 标题列表渲染 → 点击显示/替换卡片 → 三条用户故事全部通过；
2. 阶段二（打磨）：界面样式、枚举映射（餐型/难度徽标）、空数据与缺图占位处理；
3. 阶段三（进阶）：接入 TheMealDB 搜索、结果列表、无匹配警告、Save 收藏。

最终验收清单（全部来自规格文档，可直接用作测试用例）：

学习资源与项目上下文

• 规格文档在"Useful links and resources"中给出了三份核心学习材料：MDN 的Using Fetch（浏览器网络请求的权威入门）、Axios（Promise 风格的 HTTP 客户端库）以及TheMealDB API（本项目的推荐菜谱数据源）。三者分别对应"理解 Fetch API""引入第三方库简化请求""获取真实菜谱数据"三个由浅入深的学习层次。
• 规格文档还列出了一些社区实现参考，例如 Free Code Camp 的Recipe Box项目和React Recipe Box，可以在动手前观察他人对同一需求的建模与交互处理方式。
• 本仓库的每个项目文档都遵循 Example Guide 的统一模板（目标 → 用户故事 → 进阶功能 → 资源 → 示例），Recipe App 也不例外，这让整个仓库的项目规格保持了一致的可读性。

小结

Recipe App 是 app-ideas 仓库中一个典型的 Tier-1 入门项目：它以"菜谱 = 烹饪算法"的巧妙类比开场，用三条用户故事界定了最小可行产品，再用六条进阶功能铺设出通往真实 API 集成的成长路径。从本地 JSON 数据建模，到列表与卡片的单向替换交互，再到 TheMealDB 搜索与本地收藏的闭环，这个项目几乎覆盖了前端开发者入门阶段需要锤炼的全部核心能力，且每一步都有清晰可验证的验收标准。按照本文的路线图完成它，你将同时收获一个可放进作品集的应用，以及一套可复用的"数据 → 界面 → 交互"方法论。

• 文档
• 教程