第四章：开发常识与技术栈
序言
在开始写代码之前，老师傅告诉你，还有一些关键的开发常识需要提前了解。这些知识不会直接教你写代码，但会让你理解代码是如何在互联网上运行的。
技术栈选择
技术栈选型应该在 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 通常是收费的，但对开发者很友好，一般都有免费额度供你测试。你需要做的是：
获取凭证：找到官方开放平台的开发者文档，找到你需要的功能，注册账号生成 API Key（这是你的敏感凭证，切勿泄露）。老师傅特意叮嘱，一定要把 Key 保存到环境变量
.env文件中，而不是直接写死在代码里。环境变量就像是代码和密钥之间的"防火墙"，只要配置一下，程序运行时会自动去读取它们，这样既能保证功能正常，又能防止你把密钥上传到 GitHub 被人盗用。确立技术路线（SDK vs HTTP）：老师傅阻止了你让 AI 手写原始 HTTP 请求的想法。他介绍了 SDK（软件开发工具包） 的概念——官方通常已经把复杂的网络交互、错误处理和验证逻辑封装好了，只需要安装一下，找到官方文档就可以直接使用。更关键的是，官方 SDK 通常自带完善的 TypeScript 类型定义。这相当于给 AI 提供了代码指南，它能准确地知道有哪些功能可用，参数该怎么填，这比让它对着空白的 HTTP 请求瞎编要靠谱得多。
编写最小测试：配置好 SDK 和 API Key 后，老师傅说："别急着写业务功能，先让 AI 帮你写一个最简单的测试代码。"这个测试只需要做一件事：调用一次 API，看能否收到返回结果。
错误处理：老师傅提醒你注意几个常见问题。限流（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)