将 Prettier 集成到 C# MSBuild 流程以实现 GraphQL 查询文件的自动化格式化

后端技术

文章字数: 3.5k

阅读时长: 13 分

团队转向 GraphQL 后，我们很快就享受到了强类型 API 和精确数据获取带来的便利。在 C# 项目中，我们选择了 Strawberry Shake 作为客户端代码生成工具。它能根据 .graphql 文件中的查询、变更和订阅定义，自动生成类型安全的 C# 客户端代码，这极大地提升了开发效率。但一个预料之外的痛点很快浮现：.graphql 文件本身的格式一致性问题。

每个开发者的编辑器配置、插件乃至个人习惯都不同，导致提交到版本库的 .graphql 文件格式五花八门。有的用两个空格缩进，有的用四个；有的在大括号前后加空格，有的不加。这些纯粹的格式差异在代码审查（Pull Request）中产生了大量噪音，淹没了真正有价值的业务逻辑变更，审查者需要花费额外心智去分辨哪些是实质性修改，哪些只是格式调整。

我们需要的不是一份冗长的格式化规范文档，而是一个能自动强制执行的机制。在前端领域，Prettier 早已是解决这类问题的标准答案。但我们是一个 C# 团队，日常工作流围绕着 Visual Studio、Rider 和 dotnet build 命令。让整个团队去配置 Node.js 环境、学习 Prettier CLI、并记住在提交前手动运行命令，这不仅增加了认知负担，而且无法保证百分之百的执行率。预提交钩子（pre-commit hooks）是另一个选项，但它同样依赖于每个开发者本地环境的正确配置，且容易被 git commit --no-verify 绕过。

真正的解决方案必须是无感的、强制的、且与我们现有的 C# 工作流深度集成。它应该在开发者最熟悉的操作——构建项目时自动发生。这意味着，我们需要将 Prettier，一个 JavaScript 工具，无缝地嵌入到 .NET 的构建引擎 MSBuild 中。

架构决策：为何选择 MSBuild 集成

在决定最终方案前，我们评估了几个备选路径：

方案A：独立的 CI/CD 检查任务
- 实现: 在 CI 流水线中增加一个步骤，该步骤拉取代码，安装 Node.js 环境，然后运行 prettier --check 命令。如果发现未格式化的文件，构建失败。
- 优点: 与开发环境解耦，集中控制。
- 缺点: 反馈循环太长。开发者在本地提交了未格式化的代码，推送到远程，等待 CI 运行几分钟后才收到失败通知。然后需要返回本地修改、再次提交、推送，整个过程非常低效和 frustrating。
方案B：本地 Git 预提交钩子 (Husky)
- 实现: 在项目中引入 Husky，配置 pre-commit 钩子，在提交前自动运行 Prettier 格式化暂存区的文件。
- 优点: 反馈非常快，在提交时就能发现并修复问题。
- 缺点:
  - 环境依赖: 要求每个开发者的机器上都正确安装了 Node.js 和 npm/yarn。
  - 可绕过性: git commit --no-verify 可以轻易跳过检查。
  - 侵入性: 需要修改开发者本地的 .git 目录结构，有时在不同操作系统或 Git 客户端上会遇到兼容性问题。
方案C：深度集成到 MSBuild 流程
- 实现: 编写一个自定义的 MSBuild .targets 文件，定义一个新的构建目标（Target）。这个目标使用 <Exec> 任务来调用 Node.js 和 Prettier CLI。然后将此目标注入到标准的构建流程中，确保它在 GraphQL 代码生成之前执行。
- 优点:
  - 无感体验: 开发者只需执行 dotnet build 或在 IDE 中点击“生成”，格式化就会自动完成。无需额外命令或配置。
  - 强制执行: 成为构建过程的一部分，无法绕过。构建成功即意味着代码已格式化。
  - 平台一致: 无论是本地开发环境（Windows, macOS, Linux）还是 CI/CD 服务器，只要能执行 dotnet build，行为就完全一致。
  - 集中管理: 所有配置都在项目代码库中（.csproj, .targets, package.json），新成员克隆项目后即可使用。

在真实项目中，开发体验和反馈效率至关重要。方案C将格式化问题“左移”到了开发流程的最前端，提供了最即时、最无缝的体验。虽然它需要对 MSBuild 有一定的了解，但一次配置，全员受益，这是最符合我们团队工程化目标的务实选择。

逐步实现：将 Prettier 植入 `.csproj`

我们的目标项目是一个标准的 .NET 控制台应用，它引用了 Strawberry Shake 来生成 GraphQL 客户端。

第一步：项目初始结构

项目结构如下，我们将所有的 GraphQL 查询都放在 GraphQL/Queries 目录下。

/MyGraphQLApp
├── MyGraphQLApp.csproj
├── Program.cs
├── GraphQL/
│   └── Queries/
│       └── GetUserDetails.graphql
└── .graphqlrc.json

.graphqlrc.json 是 Strawberry Shake 的配置文件，指定了 schema 的位置和生成代码的命名空间。

{
  "schema": "https://my-api.com/graphql",
  "documents": "GraphQL/**/*.graphql",
  "extensions": {
    "strawberryShake": {
      "name": "MyGraphQLClient",
      "namespace": "MyGraphQLApp.GraphQL.Generated",
      "url": "https://my-api.com/graphql"
    }
  }
}

第二步：引入 Node.js 依赖

尽管是 C# 项目，我们仍需要在项目根目录下创建一个 package.json 文件来管理 Prettier 及其插件。

package.json:

{
  "version": "1.0.0",
  "name": "mygraphqlapp-devtools",
  "private": true,
  "devDependencies": {
    "prettier": "3.2.5",
    "@prettier/plugin-graphql": "0.1.5"
  }
}

我们引入了 prettier 核心库和专门用于格式化 GraphQL 文件的 @prettier/plugin-graphql 插件。将其定义为 devDependencies 是因为它们只在开发和构建时需要。

同时，添加一个 .prettierrc.json 配置文件来定义我们的格式化规则。

.prettierrc.json:

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all"
}

第三步：编写自定义 MSBuild Targets 文件

这是整个方案的核心。我们在项目根目录创建一个名为 Build.Prettier.targets 的文件。这个文件将定义格式化操作的具体逻辑。

Build.Prettier.targets:

<Project>

  <!-- 
    定义一个属性来定位 node_modules 目录。
    $(MSBuildThisFileDirectory) 是一个内置属性，表示当前 .targets 文件所在的目录。
    这确保了路径的相对性和可移植性。
  -->
  <PropertyGroup>
    <NodeModulesDir>$(MSBuildThisFileDirectory)node_modules</NodeModulesDir>
  </PropertyGroup>
  
  <!-- 
    定义一个 ItemGroup 来收集所有需要格式化的 GraphQL 文件。
    使用通配符匹配 GraphQL/Queries 目录下的所有 .graphql 文件。
  -->
  <ItemGroup>
    <GraphQLQueryFiles Include="$(MSBuildThisFileDirectory)GraphQL\**\*.graphql" />
  </ItemGroup>
  
  <!--
    核心目标：`EnsureNodeModules`
    这个目标负责运行 `npm install`。
    这里的关键是增量构建的实现，避免每次构建都重新安装依赖。
    - Inputs: 监听 `package.json` 和 `package-lock.json` 文件的变化。
    - Outputs: 定义一个标记文件 `$(NodeModulesDir)/.install-stamp`。
    
    工作原理：
    MSBuild 在执行此目标前会检查：
    1. Outputs 文件（.install-stamp）是否存在。
    2. Inputs 文件（package.json 等）的修改时间是否比 Outputs 文件新。
    
    只有当 Outputs 文件不存在，或 Inputs 文件被修改过时，此目标中的任务才会执行。
    这确保了 `npm install` 只在必要时运行，极大地提升了日常构建性能。
  -->
  <Target Name="EnsureNodeModules"
          Inputs="$(MSBuildThisFileDirectory)package.json;$(MSBuildThisFileDirectory)package-lock.json"
          Outputs="$(NodeModulesDir)/.install-stamp">

    <Message Text="[Prettier] Node modules are out of date. Running 'npm install'..." Importance="high" />
    
    <Exec Command="npm install" 
          WorkingDirectory="$(MSBuildThisFileDirectory)" 
          ConsoleToMsBuild="true">
      <Output TaskParameter="ExitCode" PropertyName="ErrorCode" />
    </Exec>

    <Error Condition="'$(ErrorCode)' != '0'" Text="[Prettier] 'npm install' failed." />

    <!-- 
      成功执行后，创建（或更新）标记文件的时间戳。
    -->
    <Touch Files="$(NodeModulesDir)/.install-stamp" AlwaysCreate="true" />
  </Target>

  <!--
    核心目标：`FormatGraphQLFiles`
    这个目标负责运行 Prettier 格式化命令。
    - DependsOnTargets="EnsureNodeModules": 确保在执行此目标前，`EnsureNodeModules` 目标已成功执行。
    - BeforeTargets="CoreCompile;GenerateGraphQLClient": 将此目标注入到核心编译和 Strawberry Shake 代码生成之前。
      这是至关重要的，我们必须在生成 C# 代码之前格式化源 .graphql 文件。
    - Condition: 仅当存在 .graphql 文件时才运行此目标，避免在没有查询文件的项目中执行。
  -->
  <Target Name="FormatGraphQLFiles"
          DependsOnTargets="EnsureNodeModules"
          BeforeTargets="CoreCompile;GenerateGraphQLClient"
          Condition="'@(GraphQLQueryFiles)' != ''">
          
    <Message Text="[Prettier] Formatting GraphQL files..." Importance="normal" />
    
    <!--
      使用 ItemGroup 将所有找到的 .graphql 文件路径拼接成一个由空格分隔的字符串。
      这是因为 Prettier CLI 可以一次性接收多个文件路径。
      @(GraphQLQueryFiles, ' ') 是 MSBuild 的 Item Transformation 语法。
    -->
    <PropertyGroup>
      <GraphQLFilesToFormat>@(GraphQLQueryFiles, ' ')</GraphQLFilesToFormat>
    </PropertyGroup>
    
    <!--
      执行 Prettier 命令。
      - `npx prettier --write`: npx 负责找到并执行 node_modules 中的 prettier，--write 表示直接修改文件。
      - `WorkingDirectory`: 确保命令在项目根目录执行，这样 Prettier 才能找到 .prettierrc.json 配置文件。
      - `IgnoreExitCode="true"`: 即使 Prettier 报告没有文件被修改（这在已格式化的文件上是正常行为），我们也不希望构建失败。
        真正的格式化错误（如语法错误）会由 Prettier 以非零退出码报告，但我们暂时不在这里处理它，
        因为我们的主要目标是格式化，而不是校验。
    -->
    <Exec Command="npx prettier --write $(GraphQLFilesToFormat)"
          WorkingDirectory="$(MSBuildThisFileDirectory)"
          IgnoreExitCode="true"
          ConsoleToMsBuild="true" />
          
  </Target>

</Project>

这段 MSBuild 代码是整个解决方案的引擎。它定义了两个目标：

EnsureNodeModules: 一个具备增量构建能力的 npm install 执行器。它通过检查输入（package.json）和输出（一个时间戳文件）来决定是否需要运行，避免了在每次构建中都执行耗时的 npm install。这是保证构建性能的关键。
FormatGraphQLFiles: 实际的格式化执行器。它依赖于 EnsureNodeModules，并确保自身在 C# 编译器和 Strawberry Shake 代码生成器运行之前执行。

第四步：在主项目中导入 Targets 文件

最后一步是让我们的 C# 项目知道这个自定义构建逻辑的存在。我们通过在 .csproj 文件中添加一个 <Import> 标签来实现。

MyGraphQLApp.csproj:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="StrawberryShake.Server" Version="13.9.0" />
  </ItemGroup>

  <!--
    在这里导入我们的自定义构建逻辑。
    MSBuild 会在处理项目时加载这个文件，并将其中的 Target 和 Property 合并到构建流程中。
  -->
  <Import Project="Build.Prettier.targets" />

</Project>

现在，整个工作流已经建立。当任何开发者在这个项目上运行 dotnet build 时：

MSBuild 开始构建 MyGraphQLApp 项目。
在执行 CoreCompile 之前，它发现了一个名为 FormatGraphQLFiles 的目标需要运行。
FormatGraphQLFiles 依赖于 EnsureNodeModules，于是 MSBuild 先执行 EnsureNodeModules。
EnsureNodeModules 检查 node_modules 是否需要更新。如果是第一次构建或 package.json 有变更，它会运行 npm install。否则，它会跳过执行，瞬间完成。
EnsureNodeModules 完成后，FormatGraphQLFiles 开始执行。它收集所有 .graphql 文件，并调用 npx prettier --write 对它们进行原地格式化。
格式化完成后，构建流程继续，Strawberry Shake 的 GenerateGraphQLClient 目标会基于这些刚刚被格式化得一尘不染的 .graphql 文件生成 C# 客户端代码。
最后，C# 编译器编译所有代码。

生产环境考量与局限性

这个方案虽然优雅，但在投入生产使用时，还需要考虑几个现实问题。

Node.js 环境依赖: 此方案的一个明显权衡是，构建环境（无论是开发者本地还是 CI 服务器）必须安装 Node.js 和 npm。对于一个纯 .NET 技术栈的团队，这可能是一个新的基础设施要求。在 CI/CD 环境中，通常需要使用包含 .NET SDK 和 Node.js 的复合构建镜像，或者在流水线中分步安装。
首次构建性能: 在一台全新的机器上，第一次构建会触发 npm install，这可能会耗时一到两分钟，具体取决于网络状况和依赖数量。这是一个一次性的成本，后续的构建由于增量检查机制会恢复到极快的速度。需要确保团队成员理解这一点。
错误处理与诊断: 当前的 <Exec> 配置相对简单。在更复杂的场景中，可能需要更精细的错误捕获。例如，如果 prettier 因为 .graphql 文件存在语法错误而执行失败，它会返回一个非零退出码。当前的 IgnoreExitCode="true" 会掩盖这个问题。一个更健壮的实现可能会捕获退出码，并根据其值输出更具诊断性的 MSBuild 警告或错误。
可维护性与封装: 目前，.targets 文件和 package.json 是散落在项目中的。如果公司内有多个项目都需要这个功能，更好的做法是将其封装成一个 NuGet 包。这个包可以包含 .targets 文件和逻辑，项目只需引用这个 NuGet 包，就可以自动获得格式化能力，而无需复制粘贴配置文件。这大大提升了方案的可复用性和可维护性。
适用边界: 此模式的核心思想——通过 MSBuild <Exec> 调用外部工具链——并不局限于 Prettier。它可以被推广到任何需要与 .NET 构建流程集成的命令行工具，例如 ESLint、Stylelint，甚至是打包前端资源的 Webpack 或 Vite。它为在 .NET 项目中管理异构工具链提供了一个强大而统一的入口。

这个方案最终被团队采纳并成功实施。它消除了关于代码风格的无谓争论，让代码审查回归其本质——关注逻辑和设计。通过将一个前端生态的优秀工具无缝集成到后端开发工作流中，我们构建了一个更高效、更一致的开发环境。这种跨技术栈的工具链整合，是现代软件工程中解决特定领域问题的务实之道。

GraphQL Client C# Prettier MSBuild DevOps

基于 Ktor 和 DDD 实现跨越 SQS 与 Envoy 的全链路追踪

2023-11-20 分布式架构

Domain-Driven Design (DDD) AWS SQS Envoy Proxy Ktor SkyWalking

构建混合实时向量存储：在Kubeflow中协同Cassandra与Pinecone的架构权衡

2023-10-27 数据工程与存储

Pinecone Cassandra Vector SQLite Kubeflow

将 Prettier 集成到 C# MSBuild 流程以实现 GraphQL 查询文件的自动化格式化

架构决策：为何选择 MSBuild 集成

逐步实现：将 Prettier 植入 .csproj

生产环境考量与局限性

逐步实现：将 Prettier 植入 `.csproj`