您现在的位置是：网站首页 > 团队协作开发规范文章详情
团队协作开发规范
陈川
【
Node.js
】
9227人已围观
4738字
在Express框架中，团队协作开发规范的制定是保证项目高效推进的关键。清晰的代码风格、统一的目录结构、严格的版本控制以及规范的接口设计，能够减少沟通成本，提升代码可维护性。以下从多个维度展开具体实践方案。
代码风格与格式化
团队必须统一代码风格，避免因个人习惯差异导致的可读性问题。推荐使用ESLint + Prettier组合，并通过配置文件固化规则。
// .eslintrc.js 示例
module.exports = {
extends: ['airbnb-base', 'prettier'],
rules: {
'no-console': 'off',
'consistent-return': 'warn',
'arrow-parens': ['error', 'as-needed']
}
};
// .prettierrc 示例
{
"semi": false,
"singleQuote": true,
"tabWidth": 2
}
要求所有成员在提交代码前执行：
npx eslint --fix src/
npx prettier --write src/
目录结构规范
采用分层架构设计，典型结构示例：
project/
├── config/ # 环境配置
│ ├── dev.js
│ └── prod.js
├── src/
│ ├── controllers/ # 路由控制器
│ ├── models/ # 数据模型
│ ├── services/ # 业务逻辑
│ ├── middlewares/ # 自定义中间件
│ ├── utils/ # 工具函数
│ └── app.js # 应用入口
├── tests/ # 测试代码
└── docs/ # 项目文档
禁止出现以下反模式：
- 在路由文件中直接写数据库操作
- 在控制器中包含超过200行的业务逻辑
- 跨层直接调用（如控制器直接调用模型）
Git协作流程
采用Git Flow工作流，具体规则：
- 功能分支命名：
feat/feature-name - 修复分支命名：
fix/issue-description - 提交信息格式：
type(scope): description - feat(authentication): add JWT support - fix(router): handle 404 cases - 代码审核要求：
- 至少1个Reviewer批准
- 必须通过CI流水线
- 禁止使用
--force推送
接口设计标准
RESTful API设计示例：
// 错误示范
app.get('/getUserList', (req, res) => {...})
// 正确示范
router.get('/users', userController.list)
router.post('/users', userController.create)
router.patch('/users/:id', userController.update)
响应格式规范：
{
"code": 200, // 业务状态码
"data": { ... }, // 有效载荷
"message": "success", // 描述信息
"requestId": "a1b2c3" // 请求追踪ID
}
必须实现以下中间件：
// 统一响应处理器
app.use((req, res, next) => {
res.apiSuccess = (data) => {
res.json({ code: 200, data })
}
res.apiError = (message) => {
res.status(400).json({ code: 400, message })
}
next()
})
错误处理机制
分层错误处理方案：
- 服务层抛出业务错误：
class UserService {
async create(userData) {
const exists = await UserModel.findOne({ email: userData.email })
if (exists) throw new BusinessError('EMAIL_EXISTS')
// ...
}
}
- 全局错误拦截器：
app.use((err, req, res, next) => {
if (err instanceof BusinessError) {
return res.status(400).json({
code: err.code,
message: err.message
})
}
// 未知错误处理
console.error(err.stack)
res.status(500).send('Internal Server Error')
})
测试覆盖率要求
单元测试必须覆盖：
- 所有控制器方法
- 核心工具函数
- 中间件逻辑
集成测试示例：
describe('User API', () => {
before(async () => {
await UserModel.deleteMany({})
})
it('POST /users should create new user', async () => {
const res = await request(app)
.post('/users')
.send({ email: 'test@example.com' })
expect(res.status).to.equal(201)
})
})
最低覆盖率标准：
- 语句覆盖率 ≥ 80%
- 分支覆盖率 ≥ 70%
- 函数覆盖率 ≥ 90%
文档编写规范
所有接口必须附带Swagger文档：
paths:
/users:
get:
tags: [User]
summary: 获取用户列表
parameters:
- $ref: '#/parameters/limitParam'
- $ref: '#/parameters/offsetParam'
responses:
200:
description: 用户列表
schema:
type: array
items:
$ref: '#/definitions/User'
代码注释要求：
/**
* 创建新用户
* @param {Object} userData - 用户数据
* @param {string} userData.email - 必须包含@符号
* @throws {BusinessError} 当邮箱已存在时抛出
* @returns {Promise<User>} 新创建的用户文档
*/
async function createUser(userData) { ... }
依赖管理策略
package.json管理原则：
- 精确版本锁定：
"dependencies": {
"express": "4.18.2",
"mongoose": "8.0.3"
}
- 开发依赖分组：
"devDependencies": {
// 测试相关
"mocha": "^10.2.0",
"chai": "^4.3.7",
// 构建相关
"webpack": "^5.88.2"
}
定期执行：
npm outdated
npx npm-check-updates -u
性能优化要点
必须实现的中间件：
// 响应时间监控
app.use((req, res, next) => {
const start = Date.now()
res.on('finish', () => {
const duration = Date.now() - start
console.log(`${req.method} ${req.url} - ${duration}ms`)
})
next()
})
// 内存泄漏防护
app.use(helmet())
app.use(compression())
app.use(express.json({ limit: '100kb' }))
禁止行为：
- 在循环中执行数据库查询
- 同步阻塞操作（如fs.readFileSync）
- 未限制数量的批量查询
安全防护措施
基础安全配置：
app.disable('x-powered-by')
app.use(cors({
origin: ['https://yourdomain.com'],
methods: ['GET', 'POST']
}))
// 速率限制
const limiter = rateLimit({
windowMs: 15 * 60 * 1000,
max: 100
})
app.use('/api/', limiter)
敏感数据处理规范：
- 密码必须bcrypt哈希：
const saltRounds = 10
const hashedPassword = await bcrypt.hash(plainPassword, saltRounds)
- 错误信息脱敏：
// 错误示范
res.status(500).send(`Database error: ${err.sqlMessage}`)
// 正确示范
res.status(500).send('Internal Server Error')
