14.3 新项目从零搭建技巧

从零开始搭建项目最忌边写边改，前期多花30分钟规划，能省后期3天返工。以下是实操建议：

1. 先定技术栈，再动手

• 锁定版本：Node、Python、JDK等主版本必须写死（如node:18.16.0），别用"latest"
• 包管理器：团队统一用pnpm/yarn/npm其中一个，配好.npmrc锁定源
• IDE配置：提前共享.editorconfig和settings.json，避免格式冲突

2. 目录结构按业务而非技术分

src/
  modules/
    user/          # 用户模块（含controller/service/dto全在内）
    order/         # 订单模块
  shared/          # 公共工具（日志、异常处理）
  config/          # 环境配置分离

比按controller/service/dao分层更利于后期微服务拆分。

3. 第一天就配好CI/CD

• 哪怕只有lint和build两步，也必须跑通GitHub Actions/GitLab CI
• 提交代码即自动检查，比人工Code Review效率高10倍

4. 环境隔离三板斧

• .env.local（本地开发，永不提交）
• .env.development（联调环境）
• .env.production（生产环境，密钥走K8s Secret或配置中心）
• 配好dotenv校验，启动时缺必填项直接报错，别等运行时才暴露

5. 日志和监控先行

• 引入winston/pino或logback，从第一行代码就区分debug/info/error
• 埋点接口耗时监控（AOP拦截或中间件），上线后排查慢接口有数据可依

6. 数据库版本管理

• 用Flyway或Liquibase管理SQL脚本，禁止手动改表
• 本地开发用Docker Compose启动MySQL/Redis，docker-compose.yml提交到仓库，确保所有人环境一致

7. 文档即代码

• README.md必须包含：一键启动命令、环境变量说明、端口占用
• 接口文档用Swagger/OpenAPI自动生成，手写文档一周就过时

避坑提醒

• 别造轮子：认证、支付、文件存储直接用成熟SDK，自研方案后期维护成本极高
• 控制依赖：npm包或Maven依赖每多一个，未来安全风险多一分，非必要不引入
• Mock数据：前端并行开发时，用json-server或Mock.js提前定义接口契约，避免等后端联调

底线原则：第一天搭建的项目，必须能在新电脑上git clone后一条命令跑起来，做不到说明文档或脚本不合格。