⚠️ Alpha内测版本警告：此为早期内部构建版本，尚不完整且可能存在错误，欢迎大家提Issue反馈问题或建议
Vibe Vibe

主题

第四章：开发常识与技术栈 ​

序言 ​

在开始写代码之前，老师傅告诉你，还有一些关键的开发常识需要提前了解。这些知识不会直接教你写代码，但会让你理解代码是如何在互联网上运行的。

技术栈选择 ​

技术栈选型应该在 PRD 确定后进行。老师傅说："先搞清楚要做什么，再决定用什么做。"

面对那么多技术选项，新手容易纠结。其实有个简单的决策框架：全栈 Next.js（AI 友好、生态成熟、部署便捷），除非你的项目是纯前端再考虑 Vite；数据库使用 PostgreSQL（关系型 + JSONB + pgvector，扩展性强）。

PostgreSQL 数据库的两种托管方式：Supabase 和 Neon 都是托管 PostgreSQL 的云服务，但定位不同。Supabase 提供完整的后端功能（认证、存储、实时订阅），适合快速开发；Neon 专注于数据库本身，轻量且支持无服务器架构，适合对后端有自定义需求的场景。如果你只想专注业务逻辑，选 Supabase；如果你需要灵活控制，选 Neon。

核心思路是"明确需求 → 评估复杂度 → 选择最小可行方案"，预留扩展空间但不过度设计。在 AI 时代，技术栈越统一，AI 的上下文理解就越准确，开发效率也越高。

4.1 技术栈决策框架 (./01-tech-stack-decision.md) 🟡 - 系统化地选择合适的技术栈

PRD 与技术文档的关系 ​

在 PRD 迭代到 5 稿、产品方案基本确定后，老师傅提醒你，除了梳理业务逻辑，你还需要记录具体的技术实现方案，也就是技术文档。

很多人容易混淆 PRD 和技术文档，其实它们的分工很明确：

PRD（产品需求文档） 回答"做什么"的问题：

  • 目标用户是谁？
  • 核心功能有哪些？
  • 用户如何交互？
  • 边缘场景怎么处理？

技术文档 回答"怎么做"的问题：

  • 用什么技术栈？（Next.js + PostgreSQL）
  • 数据库表结构怎么设计？（用户表、文章表、评论表）
  • API 接口怎么定义？（/api/auth、/api/posts）
  • 第三方服务怎么集成？（OpenAI API、地图服务）
  • 部署方案是什么？（Edgeone、Vercel、云服务器）

老师傅说："对于现在的你来说，不必拘泥于形式，完全可以将技术文档与 PRD 合并，统称为项目文档，这样查阅起来更方便。但要清楚区分哪些是产品层面的思考，哪些是技术层面的决策。"

4.2 PRD与技术文档的关系 (./02-prd-and-tech-docs.md) 🟢 - 理解产品文档与技术文档的分工

编程的基本构件 ​

老师傅说，在写代码之前，你得先明白代码是由什么构成的。就像写文章要先认识字一样，编程也有它的"基本字"。

所有编程语言，无论语法如何不同，都基于四个核心概念：变量、函数、条件和循环。

变量是存储数据的容器。你可以把它想象成一个贴有标签的盒子——盒子里装着数据，标签是变量名。

函数是可复用的指令块。当你发现自己在重复写相似的代码时，就应该把它封装成函数。函数接收输入（参数），执行操作，然后返回输出。

条件判断让程序能根据不同情况采取不同行动。if (用户已登录) { 显示欢迎信息 } else { 显示登录按钮 }——程序根据条件决定执行哪段代码。

循环让程序能重复执行某些操作。比如你要给 1000 个用户发送邮件，不需要写 1000 次发送代码，只需写一个循环："对列表中的每个用户，发送邮件"。

这四个概念是图灵完备的基础。这意味着任何可计算的问题，都可以用这四种构件的组合来解决。

4.3 如何读懂 AI 生成的代码 (./03-programming-basics.md) 🟢 - 理解代码的四个核心概念

API 与 HTTP 基础 ​

老师傅看你一脸好奇，便给你讲了前后端交互的底层原理。他说，HTTP 其实就像是一套远程办事指令系统。当你在浏览器里访问一个网站时，本质上就是你的浏览器（客户端）向远程的服务器发送了一条规范化的指令，服务器收到指令后处理完事情，再把结果按照同样的规范返回给你。

老师傅继续解释说，每条 HTTP 指令都包含四个核心部分：

第一部分是请求方法，告诉服务器你想做什么类型的事情。最常见的四种方法是：

  • GET 用于读取数据，比如查看文章列表
  • POST 用于创建新数据，比如提交注册表单
  • PUT 或 PATCH 用于修改已有数据，比如更新个人资料
  • DELETE 用于删除数据，比如注销账号

第二部分是 URL，也就是你要操作的具体资源的地址。比如 https://api.example.com/users/123，意思就是"访问 example.com 服务器上的 123 号用户"。

第三部分是 Headers（头信息），用来携带一些元数据。比如你的身份认证令牌（证明你是谁）、你期望的数据格式是什么（JSON 还是 XML）。

第四部分是 Body（主体），就是你真正要发送的数据内容，比如表单里填写的信息或一段 JSON 格式的参数。

虽然这些细节 AI 都会帮你处理，但理解这四个部分能让你更快定位问题。比如 API 返回 401 Unauthorized，你就知道是 Headers 里的令牌有问题；返回 404 Not Found，你就知道是 URL 路径写错了。

4.4 API与HTTP基础 (./04-api-and-http.md) 🟢 - 掌握 API 和 HTTP 协议的工作原理

前后端分离概念 ​

在学习 HTTP 通信的过程中，老师傅先给你解释了前端和后端这两个概念。

前端（Frontend） 是用户看到和操作的界面——浏览器里运行的代码。你在网页上看到的按钮、输入框、图片、文字，都是前端渲染出来的。当你点击按钮或输入文字时，前端代码会做出反应。

后端（Backend） 是服务器上处理数据和逻辑的代码。用户看不到它，但它负责处理前端发来的请求——比如查询数据库、验证身份、调用其他服务。处理完成后，后端把结果返回给前端，前端再展示给用户。

以前，前端和后端通常是两个独立的项目，用不同的语言写，由不同的团队维护。现在有了 Next.js 这样的全栈框架，前端和后端代码都在同一个项目里，用同一种语言（JavaScript/TypeScript）写，但它们各自的职责没有变：前端负责"展示"，后端负责"处理"。

在规划功能时，你遇到了两个必须提前考虑的问题：你想要做用户系统，这涉及到鉴权。你想要做地图功能，这涉及到外部 API。老师傅提醒你，不要把所有代码都塞在一个文件里，要学会把功能拆分成不同的模块，比如 auth（认证）、api（接口）、components（组件）。这种模块化思维是项目能长期维护的关键。

4.5 前后端分离概念 (./05-frontend-backend-separation.md) 🟢 - 理解前后端分离的架构与交互

配置文件格式 ​

在编写技术文档和配置项目的过程中，你还顺便了解了 JSON 和 YAML 这些奇怪的配置文件格式。

JSON 就像是一种严格格式化的数据表达方式。它用大括号 {} 表示对象，用方括号 [] 表示数组，数据以"键: 值"的方式组织。你可以把 JSON 理解为数字时代的普通话——不同编程语言、不同系统之间交流的通用语言。

YAML 则是一种更人性化的配置格式，它不使用括号，而是通过缩进来表示层级关系，写起来更简洁。很多配置文件（如某些 CI/CD 配置）都使用 YAML 格式。

原来，对于 AI 来说，相比于散漫的自然语言，这些结构清晰的格式才是它们最爱读的"说明书"。

4.6 配置文件格式 (./06-config-formats.md) 🟢 - 理解 JSON 和 YAML 配置格式

API 集成实战 ​

你想接入 AI 能力，或者地图服务等。老师傅告诉你，这些外部 API 通常是收费的，但对开发者很友好，一般都有免费额度供你测试。你需要做的是：

  1. 获取凭证：找到官方开放平台的开发者文档，找到你需要的功能，注册账号生成 API Key（这是你的敏感凭证，切勿泄露）。老师傅特意叮嘱，一定要把 Key 保存到环境变量 .env 文件中，而不是直接写死在代码里。环境变量就像是代码和密钥之间的"防火墙"，只要配置一下，程序运行时会自动去读取它们，这样既能保证功能正常，又能防止你把密钥上传到 GitHub 被人盗用。

  2. 确立技术路线（SDK vs HTTP）：老师傅阻止了你让 AI 手写原始 HTTP 请求的想法。他介绍了 SDK（软件开发工具包） 的概念——官方通常已经把复杂的网络交互、错误处理和验证逻辑封装好了，只需要安装一下，找到官方文档就可以直接使用。更关键的是，官方 SDK 通常自带完善的 TypeScript 类型定义。这相当于给 AI 提供了代码指南，它能准确地知道有哪些功能可用，参数该怎么填，这比让它对着空白的 HTTP 请求瞎编要靠谱得多。

  3. 编写最小测试：配置好 SDK 和 API Key 后，老师傅说："别急着写业务功能，先让 AI 帮你写一个最简单的测试代码。"这个测试只需要做一件事：调用一次 API，看能否收到返回结果。

  4. 错误处理：老师傅提醒你注意几个常见问题。限流（Rate Limit）——外部 API 通常不是无限调用的；超时处理——API 如果迟迟不响应，你的程序会卡住；认证失败——如果 API Key 过期或无效，会返回 401 Unauthorized。

4.7 API集成实战 (./07-api-integration.md) 🟢 - 从零开始集成外部 API

项目说明书 README.md ​

代码不仅是给机器运行的，也是给人和 AI 阅读的。你知道了要写 README.md。这不是冗余信息，而是项目的"说明书"。你在里面清晰地记录了如何启动项目（pnpm dev）、如何配置环境变量、核心功能的逻辑。从此，无论是谁，直接看文档就上手了。

README.md 就像是项目的"门面"，包含：

  • 项目简介：这个项目是做什么的？
  • 快速开始：如何安装依赖、启动项目
  • 环境变量：需要配置哪些密钥和参数
  • 核心功能：主要功能模块和交互逻辑
  • 技术栈：使用了哪些技术和工具
  • 贡献指南：如何参与项目开发

4.8 项目说明书结构 (./08-readme-structure.md) 🟢 - 编写完整的项目 README.md 文档

小节导航 ​

- **4.1 技术栈决策框架** (./01-tech-stack-decision.md) 🟡 - 系统化地选择合适的技术栈
- **4.2 PRD与技术文档的关系** (./02-prd-and-tech-docs.md) 🟢 - 理解产品文档与技术文档的分工
- **4.3 如何读懂 AI 生成的代码** (./03-programming-basics.md) 🟢 - 理解代码的四个核心概念
- **4.4 API与HTTP基础** (./04-api-and-http.md) 🟢 - 掌握 API 和 HTTP 协议的工作原理
- **4.5 前后端分离概念** (./05-frontend-backend-separation.md) 🟢 - 理解前后端分离的架构与交互
- **4.6 配置文件格式** (./06-config-formats.md) 🟢 - 理解 JSON 和 YAML 配置格式
- **4.7 API集成实战** (./07-api-integration.md) 🟢 - 从零开始集成外部 API
- **4.8 项目说明书结构** (./08-readme-structure.md) 🟢 - 编写完整的项目 README.md 文档

学习目标 ​

完成本章后，你将能够：

  • ✅ 理解技术栈选择的决策框架
  • ✅ 区分 PRD 与技术文档的作用
  • ✅ 理解代码的四个基本构件（变量、函数、条件、循环）
  • ✅ 掌握 HTTP 协议的基本原理
  • ✅ 理解前后端分离的概念
  • ✅ 学会集成外部 API
  • ✅ 理解 JSON 和 YAML 配置格式
  • ✅ 编写清晰的项目 README
  • ✅ 建立模块化思维

下一章：第五章：代码运行的三种状态与构建原理 (../05-build-and-runtime-modes/index.md)