采用分层+功能划分的目录结构，明确分离前后端代码；2. 遵循单一职责原则，路由、控制器、服务与模型各司其职；3. 统一命名规范并集成ESLint+Prettier保证代码风格一致；4. 使用环境变量管理配置，通过脚本实现自动化构建与并发启动服务。
全栈JavaScript项目涉及前端、后端、数据库交互、配置管理等多个层面，良好的代码结构和规范能显著提升开发效率、协作体验和后期维护性。下面从目录组织、模块划分、命名约定、工具集成等方面，给出一套实用的结构化方案。
1. 基础项目结构设计
一个清晰的目录结构是项目可维护性的第一步。推荐采用分层+功能划分的方式组织文件：
/├── src/
│ ├── api/ # 后端路由定义
│ ├── controllers/ # 业务逻辑处理
│ ├── models/ # 数据模型（如Mongoose）
│ ├── middleware/ # 自定义中间件
│ ├── config/ # 环境配置、数据库连接等
│ ├── utils/ # 工具函数
│ ├── client/ # 前端代码
│ │ ├── components/ # 可复用UI组件
│ │ ├── pages/ # 页面级组件
│ │ ├── hooks/ # 自定义React Hooks
│ │ ├── services/ # API请求封装
│ │ └── assets/ # 图片、样式等静态资源
│ └── server.js # Express/Koa主入口
├── public/ # 构建后的前端资源（生产部署）
├── tests/ # 单元与集成测试
├── .env # 环境变量
├── package.json
└── README.md
这种结构将前后端逻辑物理分离，避免混杂，同时保留统一构建流程。
2. 模块化与职责分离
每个模块应遵循单一职责原则，避免“上帝文件”。具体做法包括：
立即学习“Java免费学习笔记（深入）”；
- 路由只负责路径映射，不写业务逻辑
- 控制器调用服务层或直接操作模型，返回响应
- 模型专注数据定义和数据库操作封装
- 前端API请求统一在services中管理，便于Mock和错误处理
例如，一个用户注册流程：
// src/api/auth.jsrouter.post('/register', authController.register);
// src/controllers/authController.js
const register = async (req, res) => {
const user = await UserService.create(req.body);
res.status(201).json(user);
};
// src/services/UserService.js
const create = async (data) => {
const hashed = await hashPassword(data.password);
return User.create({...data, password: hashed});
};
3. 命名与代码风格规范
统一命名减少认知成本。建议：
- 文件夹使用小写+短横线：utils, data-processing
- JS文件使用驼峰或帕斯卡：userController.js, LoginPage.jsx
- 类和React组件用大驼峰：UserService, HeaderNav
- 私有函数以下划线开头：_validateInput()
配合ESLint + Prettier强制格式化，团队无需争论空格还是制表符。基础配置示例：
// .eslintrc.json{
"extends": ["eslint:recommended", "plugin:react/recommended"],
"rules": { "semi": ["error", "always"] }
}
4. 环境管理与构建流程
通过环境变量区分开发、测试、生产行为：
- .env.development, .env.production 分别加载
- 敏感信息不提交到版本控制
- 前端打包输出到public，由后端静态托管
典型package.json脚本：
"scripts": {"dev": "node src/server.js",
"build": "cd src/client && npm run build",
"start": "node dist/server.js"
}
开发时可用concurrently启动前后端：
"dev": "concurrently \"node src/server\" \"npm run dev --prefix src/client\""基本上就这些。结构清晰了，协作自然顺畅，后续加CI/CD、日志监控也更容易推进。
