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）：
- 创建
.env.development、.env.production等文件，定义不同环境的变量（如数据库地址、API密钥）。 - 在代码中通过
process.env读取变量，并在启动时加载对应环境的.env文件。 - 敏感信息（如密码）可存储在环境变量中，避免写入代码库。
问题 2：如何组织复杂的 API 路由文件？
解答：
- 按功能模块划分：将同类 API 分组，
userRoutes.js处理用户相关接口，orderRoutes.js处理订单接口。 - 分层设计：
- 顶层路由文件（如
index.js）负责引入和注册子路由。 - 子路由文件（如
userRoutes.js）定义具体路径和控制器方法。
- 顶层路由文件（如
- 保持扁平结构：避免路由层级过深，可合并相似
小伙伴们，上文介绍了“api 目录结构”的内容，你了解清楚吗？希望对你有所帮助，任何问题可以给我留言，让我们下期再见吧。
【版权声明】：本站所有内容均来自网络，若无意侵犯到您的权利，请及时与我们联系将尽快删除相关内容!
