Skip to content

日常开发流程 ​

典型工作流 ​

text
1. 拉最新代码 → pnpm install
2. docker compose up -d(若 DB 未起)
3. 启动后端(Java 单体 / micro-java / Python 选一)
4. build 变更过的 shared 包
5. pnpm --filter web dev(或 desktop / mobile)
6. 改代码 → 浏览器/窗口热更新

改不同模块时的注意点 ​

改 contracts(OpenAPI / SQL) ​

  1. 先改 contracts/openapi/rbac-api.yaml 或 contracts/sql/schema.sql
  2. 同步 Java Controller(server-java 或 micro-java 对应服务)/ Python router
  3. 同步 packages/shared/types 与 api-client
  4. 再改前端页面

改 shared 包 ​

包构建命令消费方
typespnpm --filter @xichen-full-stack/types buildapi-client、auth、admin
authpnpm --filter @xichen-full-stack/auth buildadmin
api-clientpnpm --filter @xichen-full-stack/api-client buildadmin、mobile
admin源码直引,无需 buildweb、desktop
componentspnpm --filter @xichen-full-stack/components buildweb、desktop 模板组件
utilspnpm --filter @xichen-full-stack/utils buildweb、desktop、mobile
instrumentpnpm --filter @xichen-full-stack/instrument buildinstrument-devtool、desktop

admin 包通过 Vite 源码引用,改完保存后 web/desktop dev 会自动热更新。

改 device-agent(C#) ​

步骤说明
驱动在 packages/device-agent/src/ 新建 DeviceAgent.Drivers.*,实现 IDeviceDriver
注册DeviceAgent.Host/Program.cs 中 AddSingleton<IDeviceDriver, ...>()
验证推荐 pnpm instrument-devtool:dev;或 pnpm device-agent:dev
前端改 @xichen-full-stack/instrument 类型/客户端后需 instrument build(或 Vite alias 源码)

C# 项目不纳入 Turbo pipeline,使用 dotnet build / 根目录 pnpm device-agent:build。

改后端 ​

  • Java 单体:packages/server-java,pnpm --filter @xichen-full-stack/server-java dev,端口 8080
  • Java 微服务:packages/micro-java,先 mvn install,再启动 auth / system / monitor / gateway(4 服务 + 网关),对外 8080;改业务后可跑 scripts/sync-from-server-java.ps1 与单体同步
  • Python:packages/server-python,改 .env 后重启 uvicorn

详见 micro-java 本地启动。

改前端应用 ​

  • Web:packages/web/src/main.ts 仅为薄入口,业务在 @xichen-full-stack/admin
  • Desktop:产品框架(Desktop);仪器业务页可选
  • instrument-devtool:调试框架(instrument-devtool),联调设备首选
  • Mobile:packages/mobile,uni-app;App 打包见 Mobile — Android

依赖升级 ​

外部 npm 包版本在 pnpm-workspace.yaml 的 catalog / catalogs.mobile 中统一维护,子包 package.json 使用 "catalog:" 引用。升级步骤:

  1. 修改 pnpm-workspace.yaml 中对应版本
  2. 根目录执行 pnpm install

详见 Monorepo — Catalog。

Turbo 命令 ​

bash
pnpm dev      # 并行启动各包 dev(含所有子包,慎用)
pnpm build    # 按依赖顺序构建(shared 先于 app)
pnpm lint     # 全仓 lint
pnpm run clean   # 仅删除各包 dist,不删 node_modules

单独启动某个包更安全:

bash
pnpm --filter web dev
pnpm --filter desktop dev
pnpm instrument-devtool:dev
pnpm --filter @xichen-full-stack/server-java dev
pnpm device-agent:dev

Git 提交建议 ​

  • 契约变更与实现变更放在同一 PR,便于 review
  • 不要提交 .env、.env.production(含 API 地址、数据库密码)
  • shared 包若改了 types,确保 api-client build 通过

相关文档 ​

Xichen Full Stack 内部文档