采用分层+功能划分的目录结构，明确分离前后端代码；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.JS
router.post(‘/register’, authController.register);

// src/services/UserService.js
const create = async (data) => {
const hashed = await hashPassword(data.password);
return User.create({…data, password: hashed});
};

3. 命名与代码风格规范

统一命名减少认知成本。建议：

代码小浣熊

代码小浣熊是基于商汤大语言模型的软件智能研发助手，覆盖软件需求分析、架构设计、代码编写、软件测试等环节

51

查看详情

• 文件夹使用小写+短横线：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、日志监控也更容易推进。