这是我第一次比较完整地按照真实项目开发流程完成一个前端项目。在开始这个项目之前我对 React、TypeScript、Vite、Ant Design 这些技术栈有一定了解也能看懂单个组件、单个函数的语句含义。但是当真正要从 0 开始做一个项目时我发现困难并不只是“某一行代码怎么写”而是如何分析一个项目需求如何把一个大功能拆成多个小功能文件应该怎么分数据结构应该怎么设计前端和后端如何联调Git 分支和 PR 应该怎么管理最后如何整理 README 和项目材料这篇博客主要记录我从需求分析、技术选型、功能拆分、开发实现、前后端联调到最后项目提交的完整过程。它更适合和我一样刚开始做项目的前端初学者希望可以给大家一个参考。项目地址[SpeakMentor AI](https://github.com/tongxin02ssd-blip/speakmentor-ai)一、项目想法和需求分析这个项目的想法来自英语口语练习场景。很多英语学习者不是完全不会英语而是缺少真实对话环境说完之后也不知道自己哪里表达得不自然。所以我希望做一个 AI 口语陪练工具让用户可以选择面试、点餐、会议等真实场景通过语音输入英文系统再给出 AI 回复、语法纠错、自然表达建议、发音反馈和量化评分。刚开始做需求分析时我没有急着写代码而是先想清楚这个项目到底要解决什么问题。它的核心不是做一个普通聊天框而是形成一次完整的口语练习体验。用户选择一个场景说一句英文系统识别用户表达AI 根据场景回复同时给出这句话的纠错、发音建议和评分。这样项目的主线就比较清楚了。因此我把项目的最小可行版本确定为用户能够选择一个场景输入或模拟输入一句英文系统生成 AI 回复并展示对应的纠错反馈和评分。先把这个主流程跑通再逐步加入真实语音识别、语音播报、后端接口和大模型 API。二、技术选型和项目架构技术栈方面前端使用 React、TypeScript、Vite 和 Ant Design。React 负责构建页面TypeScript 用来约束数据结构Vite 用来快速启动项目Ant Design 用来提高 UI 开发效率。语音识别部分使用浏览器的 Web Speech APIAI 回复播报使用浏览器内置的 SpeechSynthesis。后端使用 Node.js、Express 和 TypeScript主要负责接收前端请求、调用大模型接口并在没有 API Key 或接口失败时返回 Mock 数据。项目采用前后端分离结构。前端主要负责页面展示、用户交互、语音输入、状态管理和接口调用后端主要负责处理对话请求、调用 AI 服务、生成结构化反馈并提供 Mock fallback。前端目录中components主要放页面组件比如场景选择、语音输入、对话展示和反馈展示。它们更偏向展示层不负责太复杂的业务逻辑。App.tsx是整个前端项目的流程控制中心负责维护当前场景、对话消息、语音识别状态、AI 回复状态、纠错反馈和评分结果。刚开始看到App.tsx里有很多状态会觉得乱但如果按业务分组去理解它其实就是整个项目的数据调度中心。types用来定义核心数据结构比如一条对话消息、一次纠错反馈、一组评分结果。mocks用来生成前端 Mock 数据在没有真实接口时保证项目可以运行。hooks用来封装浏览器能力比如语音识别和语音播报。api用来封装 Axios 请求让组件不需要直接关心后端地址。utils则放一些通用工具函数例如创建对话消息、计算评分等级等。后端目录也按职责拆分。routes定义接口地址controllers处理请求参数和响应services负责业务逻辑。后端提供了/health健康检查接口和/api/dialogue对话接口。前端把用户输入的英文文本发给后端后端再返回 AI 回复、纠错反馈、发音建议和评分结果。为了后续接入真实大模型我又单独加了aiService和promptService分别负责大模型请求和 Prompt 构造。三、开发过程和功能拆分这个项目我没有一次性写完而是按照 PR 拆分来完成。第一个 PR 只做项目初始化第二个 PR 搭建页面布局后面再逐步实现场景选择、Mock 数据结构、对话记录展示、语音输入、AI 回复、纠错反馈、评分面板、语音播报、后端服务和前后端联调。这样的开发方式对初学者很友好。因为每次只做一个小功能出问题时也更容易定位。例如在语音输入功能还没有接入真实浏览器 API 之前我先做了 Mock ASR让按钮点击后可以生成一段模拟英文文本。这样可以先把页面和数据流跑通再逐步替换成真实能力。项目的核心交互是用户完成一次口语练习。用户先选择练习场景然后点击按钮进行语音输入。前端拿到识别文本后会生成一条用户消息并展示在对话区同时请求后端/api/dialogue接口。后端根据场景和用户输入返回 AI 回复、纠错反馈和评分结果。前端收到结果后把 AI 回复追加到对话区并在右侧反馈区展示语法纠错、自然表达、发音建议和量化评分。这个过程中最关键的不是某个组件怎么写而是要理解数据怎么流动。以前我总是盯着单个文件看觉得每一行代码都能看懂但合起来还是不知道项目怎么运行。后来我发现理解项目应该从用户操作出发。只要能讲清楚用户点击之后哪个组件触发事件App.tsx里哪个函数处理数据如何生成接口如何请求结果如何展示整个项目就会清楚很多。四、Mock 和 fallback 设计这个项目里我觉得最重要的设计是 Mock fallback。因为 AI 项目在演示时很容易遇到不稳定因素比如浏览器不支持语音识别、麦克风权限失败、后端没启动、API Key 没配置、大模型接口请求失败等。如果没有兜底方案Demo 很容易中断。因此我在项目里保留了多层 Mock。真实语音识别失败时可以自动使用前端 Mock ASR后端真实 AI 调用失败时会自动返回后端 Mock如果后端服务没有启动前端也会自动降级到本地 Mock。这样即使外部条件不稳定项目的核心流程仍然可以完整演示。这个设计也让我意识到项目开发不能只考虑理想情况。真实项目里接口可能失败浏览器能力可能不兼容用户权限可能被拒绝。一个体验比较完整的项目应该在失败时也能给用户清晰的反馈并尽量保证主流程不中断。五、Git、README 和项目提交这个项目我尽量采用分支和 PR 的方式开发而不是直接在 main 分支上不断修改。每个功能新建一个分支每个 PR 只做一件事并在 PR 描述里写清楚功能描述、实现思路和测试方式。这样不仅方便自己回顾也能让提交记录更规范。README 也是项目提交里很重要的一部分。一个项目如果只有代码没有说明别人很难快速理解你做了什么。我在 README 中整理了项目简介、核心功能、技术栈、启动方式、环境变量配置、Mock 模式说明和后续优化方向。尤其是 AI 项目更要说明没有 API Key 时是否可以运行后端服务如何启动接口失败时是否有 fallback。通过这个过程我发现“项目完整度”不仅体现在功能数量上也体现在项目是否能被别人顺利运行和理解。代码能跑是一方面别人能看懂项目定位、启动方式和核心流程也同样重要。六、我的收获和给初学者的建议通过 SpeakMentor AI 这个项目我最大的收获不是学会了某一个 API而是第一次比较完整地体验了前端项目从 0 到 1 的开发过程。它让我意识到项目能力和语法能力是不一样的。语法能力是知道代码怎么写项目能力是知道为什么要这样拆分、数据为什么这样流动、文件为什么这样组织以及功能失败时应该怎么兜底。如果你也是刚开始做前端项目我的建议是不要一开始就追求很大的项目也不要只停留在看教程。可以选择一个小而完整的主题先把主流程跑通再一点点补充功能。先用 Mock 数据完成页面和交互再逐步接入真实 API。这样既不会一开始就被复杂技术劝退也能比较完整地体验项目开发流程。做项目时也不要只盯着某个文件逐行看。更有效的方式是从用户操作出发思考这个操作会触发哪个函数数据会保存在哪里会传给哪个组件最后显示在页面的什么位置。当你能讲清楚这个过程时你就不只是“跟着代码写”而是真的开始理解前端工程了。第一个项目最重要的不是代码多高级而是完整走完一遍。从需求分析、页面设计、组件拆分、Mock 数据、接口联调到 README 和 GitHub 提交每一步都会让你对前端开发有更具体的认识。走完之后再回头看 React、TypeScript、组件拆分和接口请求会比单纯刷语法题理解得更深入。