FullStack Dart：Server、Client CI/CD 最佳实践

my_fullstack_project/
├── 📂 client/              # Flutter 客户端应用
│   ├── lib/
│   └── pubspec.yaml
│
├── 📂 server/              # Dart 后端服务 (例如使用 Shelf)
│   ├── bin/
│   │   └── server.dart
│   └── pubspec.yaml
│
├── 📂 shared/             # 前后端共享代码
│   ├── lib/
│   │   └── src/
│   │       └── models.dart
│   └── pubspec.yaml
│
└── 📜 pubspec.yaml          # 根 pubspec，用于定义 Workspace

# my_fullstack_project/pubspec.yaml
name: my_fullstack_project_workspace
publish_to: 'none'

environment:
  sdk: '>=3.0.0 <4.0.0'

# 声明工作区包含的包
workspace:
  - client
  - server
  - shared

# client/pubspec.yaml 或 server/pubspec.yaml
name: client # or server
# ...
dependencies:
  # ...其他依赖
  
  # 通过相对路径引用共享包
  shared:
    path: ../shared

// shared/lib/src/models.dart
class User {
  final String id;
  final String email;

  User({required this.id, required this.email});

  factory User.fromJson(Map<String, dynamic> json) {
    return User(id: json['id'], email: json['email']);
  }

  Map<String, dynamic> toJson() {
    return {'id': id, 'email': email};
  }
}

# --- 阶段一：构建 ---
# 使用官方 Dart 镜像作为构建环境，它包含了完整的 SDK
FROM dart:stable AS build

# 接收一个构建参数，用于版本注入
ARG APP_VERSION=local-dev

WORKDIR /app

# 关键：由于我们使用了 workspace，需要将所有相关的代码都复制进来
# 以便在构建时能够访问到 shared 包
COPY pubspec.yaml .
COPY server/ ./server/
COPY shared/ ./shared/

# 在工作区根目录运行 `dart pub get`
RUN dart pub get

# 运行 build_runner（如果 shared 或 server 包需要代码生成，应该在模块级别运行）
RUN dart run build_runner build --delete-conflicting-outputs

# 切换到 server 目录，将 Dart 服务编译成单个可执行文件
WORKDIR /app/server
RUN dart compile exe bin/server.dart -o /app/build/server \
    -DAPP_VERSION="$APP_VERSION"

# --- 阶段二：运行 ---
# 使用一个极简的基础镜像，如 debian-slim
FROM debian:stable-slim

# 安装 Dart 可执行文件所需的最小依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# 只从构建阶段复制最终生成的可执行文件
COPY --from=build /app/build/server /app/bin/server

# 赋予执行权限
RUN chmod +x /app/bin/server

# 暴露端口
EXPOSE 8080

# 启动服务
CMD ["/app/bin/server"]

class AppConfig {
  // 从 'SERVER_URL' 环境变量读取服务器地址
  // 如果没有提供，则使用默认值
  static const serverUrl = String.fromEnvironment(
    'SERVER_URL',
    defaultValue: 'http://127.0.0.1:8080',
  );

  // 同理，读取应用版本
  static const appVersion = String.fromEnvironment(
    'APP_VERSION',
    defaultValue: 'local-dev',
  );
}

# 在 CI/CD 脚本中构建应用
flutter build appbundle --release \
  --dart-define=APP_VERSION=${{ github.ref_name }} \
  --dart-define=SERVER_URL=${{ secrets.PROD_SERVER_URL }}

# .github/workflows/release.yml
name: Full-Stack Release CI

on:
  push:
    tags:
      - 'v*'

jobs:
  build_and_deploy_server:
    name: Build and Deploy Server
    runs-on: ubuntu-latest
    # 如果标签名包含 '-server' 或者不包含 '-client'，则执行此 job
    if: ${{ contains(github.ref_name, '-server') || !contains(github.ref_name, '-client') }}
    steps:
      # ... (后端构建和部署步骤)

  build_and_archive_client:
    name: Build and Archive Client
    runs-on: windows-latest # 或 macos-latest
    # 如果标签名包含 '-client' 或者不包含 '-server'，则执行此 job
    if: ${{ contains(github.ref_name, '-client') || !contains(github.ref_name, '-server') }}
    steps:
      # ... (前端构建和归档步骤)

# 在 build_and_deploy_server job 中
steps:
  # ... (检出代码，登录 Docker 仓库，构建并推送 Docker 镜像)
  - name: Build and push Docker image
    uses: docker/build-push-action@v5
    with:
      # ...
      tags: registry.example.com/my-org/my-app:${{ github.ref_name }}, registry.example.com/my-org/my-app:latest
      build-args: |
        APP_VERSION=${{ github.ref_name }}

  - name: Trigger remote deployment
    env:
      # 将 SSH 凭证存放在 secrets 中，格式如 user:password@host:port，亦支持额外的 Base64 编码形式
      SSH_DESTINATION: ${{ secrets.SSH_DESTINATION }}
    run: |
      # 下载 ci-transfer 工具
      wget https://github.com/corkine/ci-transfer/releases/latest/download/ci-transfer
      chmod +x ci-transfer
      
      # 使用 ci-transfer 通过 SSH 执行服务器上的部署脚本
      # --source 只是为了满足命令格式，可以是一个空文件
      # 核心是 --commands 参数
      echo "Triggering deployment" > trigger.txt
      ./ci-transfer --source ./trigger.txt --destination "$SSH_DESTINATION" --commands "/path/to/your/deploy.sh"

# 在 build_and_archive_client job 中
steps:
  # ... (检出代码，设置 Flutter 环境，`dart pub get`, `dart run build_runner build`)
  - name: Build Flutter App
    run: |
      flutter build windows --release \
        --dart-define=APP_VERSION=${{ github.ref_name }} \
        --dart-define=SERVER_URL=${{ secrets.SERVER_URL }}
  
  - name: Package build artifact
    run: Compress-Archive -Path client/build/windows/x64/runner/Release/* -DestinationPath client-build.zip

  - name: Upload artifact to OSS
    shell: pwsh
    env:
      # 将 OSS 的配置（bucket, endpoint, key, secret 等）作为 JSON 字符串通过 Base64 编码存在 secrets 中
      OSS_DESTINATION: ${{ secrets.OSS_DESTINATION }}
    run: |
      # 下载 ci-transfer Windows 版本
      Invoke-WebRequest -Uri https://github.com/corkine/ci-transfer/releases/latest/download/ci-transfer.exe -OutFile ci-transfer.exe
      
      # 使用 ci-transfer 将打包好的 zip 文件上传到对象存储
      ./ci-transfer.exe -s client-build.zip --oss-destination "$env:OSS_DESTINATION"