api 目录结构

API 目录结构设计（详细版）

项目根目录

目录/文件名	功能说明	示例路径	备注
package.json	项目依赖管理和脚本配置（Node.js 示例）	/package.json	包含 scripts 字段定义构建/启动命令
.env	环境变量配置文件（如数据库连接、端口号等）	/.env	配合 dotenv 库加载环境变量
README.md	项目说明文档（含 API 使用指南、技术栈、部署方式等）	/README.md	建议包含 API 测试工具（如 Postman）链接
dist/	构建后的输出目录（前端静态资源或后端编译文件）	/dist/	后端可存放编译后的二进制文件
src/	源代码目录（核心逻辑）	/src/	推荐使用分层架构

---

前端源码（可选，若为前后端分离项目）

目录/文件名	功能说明	示例路径	备注
public/	静态资源（CSS、JS、图片等）	/src/public/	可包含预构建的前端框架（如 React/Vue）
components/	UI 组件库	/src/components/	按功能模块划分组件
services/	API 请求封装（如 Axios 实例）	/src/services/	统一管理 HTTP 请求逻辑
router/	前端路由配置（单页应用）	/src/router/	使用 Vue Router/React Router 等工具

---

后端源码

目录/文件名	功能说明	示例路径	备注
index.js	应用入口文件	/src/index.js	启动 Express/Koa 服务器
config/	配置文件（数据库、中间件、路由等）	/src/config/	按环境拆分（default.js, prod.js）
controllers/	路由处理逻辑（API 接口函数）	/src/controllers/	按功能模块划分（如 userController.js）
middlewares/	自定义中间件（权限校验、日志记录等）	/src/middlewares/	复用性高的功能抽离
models/	数据模型（数据库表结构定义）	/src/models/	ORM 工具（如 Sequelize/TypeORM）
routes/	路由定义（API 路径与控制器绑定）	/src/routes/	按业务模块划分（如 authRoutes.js）
utils/	工具函数（加密、格式化、文件操作等）	/src/utils/	通用功能抽离

---

配置与脚本

目录/文件名	功能说明	示例路径	备注
.env.*	多环境配置文件（开发、测试、生产）	/.env.development	配合 dotenv 库动态加载
scripts/	启动/构建脚本（如启动服务器、数据库迁移等）	/scripts/start.sh	支持跨平台（Windows/Linux）
logs/	日志文件（错误日志、访问日志等）	/logs/	按日期分割日志文件

---

测试代码

目录/文件名	功能说明	示例路径	备注
test/	单元测试与集成测试代码	/test/	使用 Jest/Mocha/Supertest 等工具
mock/	模拟数据与服务（如模拟数据库、第三方 API）	/test/mock/	避免依赖外部服务

---

其他辅助目录

目录/文件名	功能说明	示例路径	备注
docs/	API 文档（Swagger/Markdown 格式）	/docs/api.md	推荐使用 Swagger UI 自动生成
migrations/	数据库迁移脚本（如 Sequelize）	/migrations/	按时间戳命名迁移文件
.gitignore	Git 忽略文件	/.gitignore	排除 node_modules、日志等无关文件

---

相关问题与解答

问题 1：如何管理不同环境的配置差异？

解答：
推荐使用 .env 文件配合环境变量工具（如 dotenv）：

1. 创建 .env.development、.env.production 等文件，定义不同环境的变量（如数据库地址、API密钥）。
2. 在代码中通过 process.env 读取变量，并在启动时加载对应环境的 .env 文件。
3. 敏感信息（如密码）可存储在环境变量中，避免写入代码库。

---

问题 2：如何组织复杂的 API 路由文件？

解答：

1. 按功能模块划分：将同类 API 分组，userRoutes.js 处理用户相关接口，orderRoutes.js 处理订单接口。
2. 分层设计：
   • 顶层路由文件（如 index.js）负责引入和注册子路由。
   • 子路由文件（如 userRoutes.js）定义具体路径和控制器方法。
3. 保持扁平结构：避免路由层级过深，可合并相似

小伙伴们，上文介绍了“api 目录结构”的内容，你了解清楚吗？希望对你有所帮助，任何问题可以给我留言，让我们下期再见吧。