第四章：你必须知道的开发基础
序言
在开始写代码之前，老师傅告诉你，还有一些关键的开发常识需要提前了解。这些知识不会直接教你写代码，但会让你理解代码是如何在互联网上运行的。
代码运行的三种状态
老师傅首先给你讲了代码的"生命状态"：Dev（开发）、Build（构建）、Production（生产）。
Dev 模式就像打草稿，保存代码后浏览器自动更新，方便调试。Build 模式像把草稿印刷成书，压缩优化代码。Production 模式模拟正式环境，运行构建后的版本。
理解这三种状态能避免很多困惑：比如为什么改了代码没效果（可能在错误的模式下），或者为什么别人看不到你的本地演示（Dev 模式不适合演示）。
4.0 代码运行的三种状态 🟢 - 理解 Dev、Build、Production 三种运行模式
技术栈选择
技术栈选型应该在 PRD 确定后进行。老师傅说："先搞清楚要做什么，再决定用什么做。"
面对那么多技术选项，新手容易纠结。其实有个简单的决策框架：全栈 Next.js（AI 友好、生态成熟、部署便捷），除非你的项目是纯前端再考虑 Vite；数据库使用 PostgreSQL（关系型 + JSONB + pgvector，扩展性强）。
PostgreSQL 数据库的两种托管方式：Supabase 和 Neon 都是托管 PostgreSQL 的云服务，但定位不同。Supabase 提供完整的后端功能（认证、存储、实时订阅），适合快速开发；Neon 专注于数据库本身，轻量且支持无服务器架构，适合对后端有自定义需求的场景。如果你只想专注业务逻辑，选 Supabase；如果你需要灵活控制，选 Neon。
PostgreSQL 通过扩展支持更多功能，如 JSONB（存储 JSON 数据）和 pgvector（向量搜索，需单独安装扩展）。
核心思路是"明确需求 → 评估复杂度 → 选择最小可行方案"，预留扩展空间但不过度设计。在 AI 时代，技术栈越统一，AI 的上下文理解就越准确，开发效率也越高。
4.1 技术栈决策框架 🟡 - 系统化地选择合适的技术栈
编程的基本构件
老师傅说，在写代码之前，你得先明白代码是由什么构成的。就像写文章要先认识字一样，编程也有它的"基本字"——变量、函数、条件和循环。所有编程语言，无论语法如何不同，都基于这四个核心概念。变量存储数据，函数封装可复用的逻辑，条件让程序能根据不同情况采取行动，循环让程序能批量处理重复任务。这四个概念是图灵完备的基础，任何可计算的问题都可以用它们的组合来解决。
4.3 如何读懂 AI 生成的代码 🟢 - 理解代码的四个核心概念
PRD 与技术文档的关系
在 PRD 迭代到 5 稿、产品方案基本确定后，老师傅提醒你，除了梳理业务逻辑，你还需要记录具体的技术实现方案，也就是技术文档。
很多人容易混淆 PRD 和技术文档，其实它们的分工很明确：
PRD（产品需求文档） 回答"做什么"的问题：
- 目标用户是谁？
- 核心功能有哪些？
- 用户如何交互？
- 边缘场景怎么处理？
技术文档 回答"怎么做"的问题：
- 用什么技术栈？（Next.js + PostgreSQL）
- 数据库表结构怎么设计？（用户表、文章表、评论表）
- API 接口怎么定义？（/api/auth、/api/posts）
- 第三方服务怎么集成？（AI API、地图服务）
- 部署方案是什么？（Edgeone、Vercel、云服务器）
老师傅说："对于现在的你来说，不必拘泥于形式，完全可以将技术文档与 PRD 合并，统称为项目文档，这样查阅起来更方便。但要清楚区分哪些是产品层面的思考，哪些是技术层面的决策。"
4.2 从 PRD 到技术文档 🟢 - 理解产品文档与技术文档的分工
API 与 HTTP 基础
老师傅看你一脸好奇，便给你讲了前后端交互的底层原理。他说，HTTP 就像一套远程办事指令系统——浏览器向服务器发送规范化的指令，服务器处理完再把结果返回。每条指令包含四个部分：请求方法（GET/POST/PUT/DELETE 等，表示做什么操作）、URL（资源的地址）、Headers（身份认证等元数据）、Body（发送的数据内容）。理解这四个部分能让你更快定位问题：返回 401 是未认证（需要登录），403 是无权限（登录了但无权访问），404 是资源不存在（地址错误或资源已删除）。虽然 AI 会帮你处理细节，但懂原理才能排查问题。
4.4 API与HTTP基础 🟢 - 掌握 API 和 HTTP 协议的工作原理
前后端分离概念
在学习 HTTP 通信的过程中，老师傅先给你解释了前端和后端这两个概念。
前端（Frontend） 是用户看到和操作的界面——浏览器里运行的代码。你在网页上看到的按钮、输入框、图片、文字，都是前端渲染出来的。当你点击按钮或输入文字时，前端代码会做出反应。
后端（Backend） 是服务器上处理数据和逻辑的代码。用户看不到它，但它负责处理前端发来的请求——比如查询数据库、验证身份、调用其他服务。处理完成后，后端把结果返回给前端，前端再展示给用户。
以前，前端和后端通常是两个独立的项目，用不同的语言写，由不同的团队维护。现在有了 Next.js 这样的全栈框架，前端和后端代码都在同一个项目里，用同一种语言（JavaScript/TypeScript）写，但它们各自的职责没有变：前端负责"展示"，后端负责"处理"。
在规划功能时，你遇到了两个必须提前考虑的问题：你想要做用户系统，这涉及到鉴权。你想要做地图功能，这涉及到外部 API。老师傅提醒你，不要把所有代码都塞在一个文件里，要学会把功能拆分成不同的模块，比如 auth（认证）、api（接口）、components（组件）。这种模块化思维是项目能长期维护的关键。
4.5 前后端分离概念 🟢 - 理解前后端分离的架构与交互
配置文件格式
在编写技术文档和配置项目的过程中，你还顺便了解了 JSON 和 YAML 这些奇怪的配置文件格式。
JSON 就像是一种严格格式化的数据表达方式。它用大括号 {} 表示对象，用方括号 [] 表示数组，数据以"键: 值"的方式组织。你可以把 JSON 理解为数字时代的普通话——不同编程语言、不同系统之间交流的通用语言。
YAML 则是一种更人性化的配置格式，它不使用括号，而是通过缩进来表示层级关系，写起来更简洁。很多配置文件（如某些 CI/CD 配置）都使用 YAML 格式。
原来，对于 AI 来说，相比于散漫的自然语言，这些结构清晰的格式才是它们最爱读的"说明书"。
4.6 配置文件格式 🟢 - 理解 JSON 和 YAML 配置格式
API 集成实战
你想接入 AI 能力，或者地图服务等。老师傅告诉你，集成外部 API 有六个步骤：获取凭证、选择 SDK、配置环境变量、编写最小测试、归档参考文档、处理常见错误。
老师傅特意叮嘱，一定要把 API Key 保存到环境变量 .env 文件中，而不是直接写死在代码里。环境变量就像是代码和密钥之间的"防火墙"。
对于 AI 应用，老师傅推荐使用 Vercel AI SDK。它提供 @ai-sdk/openai-compatible 包，可以对接任何兼容 OpenAI API 格式的服务商。你只需要学习一套 API 规范，修改 baseURL、API Key 和模型名称即可调用全球主流大模型。
测试通过后，记得把官方文档保存下来。下次让 AI 写功能时，直接把文档喂给它，生成的代码更准确。
4.7 API集成实战 🟢 - 从零开始集成外部 API
项目说明书 README.md
代码不仅是给机器运行的，也是给人和 AI 阅读的。你知道了要写 README.md。这不是冗余信息，而是项目的"说明书"。你在里面清晰地记录了如何启动项目（pnpm dev）、如何配置环境变量、核心功能的逻辑。从此，无论是谁，直接看文档就上手了。
README.md 就像是项目的"门面"，包含：项目简介、快速开始、环境变量、核心功能、技术栈、贡献指南。
4.8 项目说明书结构 🟢 - 编写完整的项目 README.md 文档
学习目标
完成本章后，你将能够：
- ✅ 理解代码运行的三种状态
- ✅ 理解技术栈选择的决策框架
- ✅ 区分 PRD 与技术文档的作用
- ✅ 理解代码的四个基本构件（变量、函数、条件、循环）
- ✅ 掌握 HTTP 协议的基本原理
- ✅ 理解前后端分离的概念
- ✅ 学会集成外部 API
- ✅ 理解 JSON 和 YAML 配置格式
- ✅ 编写清晰的项目 README
- ✅ 建立模块化思维
上一章：第三章：产品思维与文档驱动