--- title: "第四章：你必须知道的开发基础" --- # 第四章：你必须知道的开发基础 ![img](/images/Advanced/mlkzwcw8-aa8ae9e1ebb5251a.jpg) ## 序言 在开始写代码之前，老师傅告诉你，还有一些关键的开发常识需要提前了解。这些知识不会直接教你写代码，但会让你理解代码是如何在互联网上运行的。 ### 代码运行的三种状态 老师傅首先给你讲了代码的"生命状态"：**Dev（开发）、Build（构建）、Production（生产）**。 Dev 模式就像打草稿，保存代码后浏览器自动更新，方便调试。Build 模式像把草稿印刷成书，压缩优化代码。Production 模式模拟正式环境，运行构建后的版本。 理解这三种状态能避免很多困惑：比如为什么改了代码没效果（可能在错误的模式下），或者为什么别人看不到你的本地演示（Dev 模式不适合演示）。 > [4.0 代码运行的三种状态](./00-build-basics.md) 🟢 - 理解 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 技术栈决策框架](./01-tech-stack-decision.md) 🟡 - 系统化地选择合适的技术栈 ### 编程的基本构件 老师傅说，在写代码之前，你得先明白代码是由什么构成的。就像写文章要先认识字一样，编程也有它的"基本字"——**变量**、**函数**、**条件**和**循环**。所有编程语言，无论语法如何不同，都基于这四个核心概念。变量存储数据，函数封装可复用的逻辑，条件让程序能根据不同情况采取行动，循环让程序能批量处理重复任务。这四个概念是**图灵完备**的基础，任何可计算的问题都可以用它们的组合来解决。 > [4.3 如何读懂 AI 生成的代码](./03-programming-basics.md) 🟢 - 理解代码的四个核心概念 ### PRD 与技术文档的关系 在 PRD 迭代到 5 稿、产品方案基本确定后，老师傅提醒你，除了梳理业务逻辑，你还需要记录具体的技术实现方案，也就是**技术文档**。 很多人容易混淆 PRD 和技术文档，其实它们的分工很明确： **PRD（产品需求文档）** 回答"做什么"的问题： - 目标用户是谁？ - 核心功能有哪些？ - 用户如何交互？ - 边缘场景怎么处理？ **技术文档** 回答"怎么做"的问题： - 用什么技术栈？（Next.js + PostgreSQL） - 数据库表结构怎么设计？（用户表、文章表、评论表） - API 接口怎么定义？（/api/auth、/api/posts） - 第三方服务怎么集成？（AI API、地图服务） - 部署方案是什么？（Edgeone、Vercel、云服务器） 老师傅说："对于现在的你来说，不必拘泥于形式，完全可以将技术文档与 PRD 合并，统称为**项目文档**，这样查阅起来更方便。但要清楚区分哪些是产品层面的思考，哪些是技术层面的决策。" > [4.2 从 PRD 到技术文档](./02-prd-and-tech-docs.md) 🟢 - 理解产品文档与技术文档的分工 ### API 与 HTTP 基础 老师傅看你一脸好奇，便给你讲了**前后端交互**的底层原理。他说，**HTTP** 就像一套远程办事指令系统——浏览器向服务器发送规范化的指令，服务器处理完再把结果返回。每条指令包含四个部分：**请求方法**（GET/POST/PUT/DELETE 等，表示做什么操作）、**URL**（资源的地址）、**Headers**（身份认证等元数据）、**Body**（发送的数据内容）。理解这四个部分能让你更快定位问题：返回 `401` 是未认证（需要登录），`403` 是无权限（登录了但无权访问），`404` 是资源不存在（地址错误或资源已删除）。虽然 AI 会帮你处理细节，但懂原理才能排查问题。 > [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 有六个步骤：获取凭证、选择 SDK、配置环境变量、编写最小测试、归档参考文档、处理常见错误。 老师傅特意叮嘱，**一定要把 API Key 保存到环境变量 `.env` 文件中**，而不是直接写死在代码里。环境变量就像是代码和密钥之间的"防火墙"。 对于 AI 应用，老师傅推荐使用 **Vercel AI SDK**。它提供 `@ai-sdk/openai-compatible` 包，可以对接任何兼容 OpenAI API 格式的服务商。你只需要学习一套 API 规范，修改 `baseURL`、API Key 和模型名称即可调用全球主流大模型。 测试通过后，记得把官方文档保存下来。下次让 AI 写功能时，直接把文档喂给它，生成的代码更准确。 > [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 文档 --- ### 学习目标 完成本章后，你将能够： - ✅ 理解代码运行的三种状态 - ✅ 理解技术栈选择的决策框架 - ✅ 区分 PRD 与技术文档的作用 - ✅ 理解代码的四个基本构件（变量、函数、条件、循环） - ✅ 掌握 HTTP 协议的基本原理 - ✅ 理解前后端分离的概念 - ✅ 学会集成外部 API - ✅ 理解 JSON 和 YAML 配置格式 - ✅ 编写清晰的项目 README - ✅ 建立模块化思维 --- --- **上一章**：[第三章：产品思维与文档驱动](../03-prd-doc-driven/index.md) **下一章**：[第五章：界面(UI)与交互(UX)](../05-ui-ux/index.md)