本地开发

安装 Node.js

请先在本机安装 Node.js v22.18.0。

提示

推荐使用 nvm 或 nvm-windows 进行安装，这样便于在不同项目中切换不同的 Node.js 版本。

检查环境变量

检查项目根目录下的 .env 和其他的 .env.* 文件，确保已经配置好环境变量。尤其是数据库配置。

开启本地服务

具体命令如下：

若要使用 int 环境进行本地开发：

npm run dev:int

若要使用 pre 环境进行本地开发：

npm run dev:pre

若要使用 production 环境进行本地开发：

npm run dev:production

开始本地开发

当你开启本地服务后，程序会自动打开系统默认浏览器访问 http://localhost:9000 网址。

说明

其实此时程序会开启多个端口，比如每个子应用对应的服务都会有一个自己的端口，但我们统一用 9000 端口代理了这些端口，这样开发者就不用考虑前后端项目端口号不一致带来的跨域问题了。

数据库迁移

生成迁移文件

npx knex migrate:make temp --knexfile knexfile.mts --env production -x mts --stub node_modules/knex/lib/migrations/migrate/stub/ts.stub

运行数据库迁移

cross-env MODE=int NODE_ENV=production npx knex migrate:latest --knexfile knexfile.mts --env production

回滚迁移

cross-env MODE=int NODE_ENV=production npx knex migrate:rollback --knexfile knexfile.mts --env production

构建和部署

构建所有应用

# 构建所有应用（以生产环境为例）
npm run build:production

# 构建特定应用（以生产环境为例）
npm run build:admin:production
npm run build:account:production
# ... 等等

# 构建并部署到生产环境
npm run buildAndDeploy:production

开发建议

1. 添加新功能

1. 确定功能模块：确定属于哪个业务模块
2. 设计数据库表：在 src/models/ 中创建模型定义文件
3. 创建数据库迁移：在 migrations/ 中创建迁移文件
4. 实现业务逻辑：在 src/services/ 中实现服务层，通常会调用 src/models/ 下定义的数据库操作方法。
5. 创建控制器：在 src/controllers/ 中创建控制器
6. 定义路由：在 src/routes/ 中定义路由
7. 前端实现：在 apps/ 下对应的前端子应用里实现前端页面，在 apps-home/ 下实现需要独立域名部署的前端静态项目。
8. 类型定义：在 typings/ 中定义相关类型

2. 代码规范

• 使用 TypeScript 严格模式
• 遵循 ESLint 规则
• 使用有意义的变量和函数名
• 添加必要的注释
• 保持代码简洁

3. 测试建议

• 数据库操作使用事务
• 使用 forUpdate() 锁定行，避免并发问题
• 金额计算使用 BigNumber，避免精度问题
• 验证所有用户输入

4. 性能优化

• 数据库查询使用索引
• 合理使用缓存
• 避免 N+1 查询问题
• 使用分页查询大量数据

常见问题

1. 如何添加新的前端应用？

1. 在 apps/ 目录下创建新应用目录
2. 参考其他应用的 vite.config.mts 配置
3. 在 package.json 中添加开发脚本
4. 在 src/app.mts 中添加代理配置

2. 如何添加新的数据库表？

1. 在 src/models/ 中创建模型文件
2. 在 migrations/ 中创建迁移文件
3. 运行迁移：npx knex migrate:latest
4. 在 typings/ 中添加类型定义

3. 如何添加新的 API 接口？

1. 在 src/services/ 中实现业务逻辑
2. 在 src/controllers/ 中创建控制器
3. 在 src/routes/ 中定义路由
4. 在 src/routes/index.mts 中注册路由

4. 如何配置环境变量？

1. 在 .env 或 .env.int、.env.pre、.env.production 中定义变量（如果是通用的变量就定义到 .env 中，否则定义到具体的环境对应的文件中）。
2. 在 src/scripts/ConstantUtils.mts 中添加常量定义
3. 在代码中使用该常量