从 WCF 迁移到 gRPC 与 REST

1. 技术债与迁移决策

一句话总结： WCF 客户端在 .NET Core 之后只支持有限子集，服务端则完全没有官方支持，迁移不是「要不要做」而是「先做哪部分」。

WCF 在 .NET Framework 时代是统一的通信框架：同一份服务契约可以暴露为 HTTP、TCP、命名管道，可以切换 SOAP 与二进制编码，可以叠加 WS-Security、WS-ReliableMessaging 等一整套 WS-* 规范。它的强大与复杂是一体两面——大部分项目只用了其中很小一部分，却背上了全部的配置复杂度。

迁移的现实驱动力有三个：

1. 运行时支持缺失。System.ServiceModel 在 .NET Core / .NET 5+ 上的服务端支持从未提供，客户端支持也限于 BasicHttpBinding、NetTcpBinding 等少数绑定，且不支持 WS-* 扩展。
2. 生态与工具链。新版本的诊断工具、容器化、AOT、可观测性库都以 ASP.NET Core 为前提。
3. 人才与维护。熟悉 WCF 配置体系（web.config 中的 bindings、behaviors、endpoints 三件套）的工程师越来越少。

迁移前的第一步不是写代码，而是盘点契约：

盘点结论通常分为三类：可直接迁移（BasicHttpBinding + 简单数据契约）、需改造后迁移（会话、事务、回调）、保留不动（依赖 WS-* 且短期无改造计划）。把第三类明确圈出来，是控制迁移范围的关键。

2. 契约映射与兼容

一句话总结： DataContract 到 Protobuf 的映射不是一对一，枚举、可空、多态与字段编号都需要显式设计，且必须保证新旧客户端同时可用。

服务契约的映射关系：

一个典型的映射示例：

// WCF 契约
[ServiceContract]
public interface IOrderService
{
    [OperationContract]
    OrderDto GetOrder(string orderId);

    [OperationContract]
    void SubmitOrder(SubmitOrderRequest request);
}

syntax = "proto3";

option csharp_namespace = "Orders.Api";

service OrderService {
  rpc GetOrder (GetOrderRequest) returns (OrderReply);
  rpc SubmitOrder (SubmitOrderRequest) returns (SubmitOrderReply);
}

message GetOrderRequest {
  string order_id = 1;
}

message OrderReply {
  string order_id = 1;
  string title = 2;
  double total = 3;
  OrderStatus status = 4;
  repeated OrderItem items = 5;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PAID = 2;
}

几个必须显式处理的差异：

1. 枚举必须从 0 开始且 0 为未指定。proto3 的枚举默认值是 0，而 WCF 的 enum 默认值是第一个成员。若原契约里 Pending = 1，映射后「未设置」与「Pending」无法区分。
2. DateTime 没有原生类型。用 google.protobuf.Timestamp 而非 int64 时间戳字符串，否则时区语义会丢失。
3. 可空性不同。proto3 的标量字段没有 null，需要显式 optional（会生成 HasValue）。WCF 的 Nullable<T> 迁移时容易变成「0 与 null 不分」。
4. 多态不支持。[KnownType] 的继承体系在 Protobuf 中需要用 oneof 重新建模，或在消息中加类型判别字段。

2.1 字段编号与兼容性纪律

一句话总结： Protobuf 的字段编号一旦发布就不能复用，删除字段必须保留编号占位，这是契约演进的唯一纪律。

Protobuf 的兼容性规则与 JSON 完全不同，必须提前建立纪律：

• 字段编号是契约。编号不变则向后兼容，改编号等于改字段名。
• 删除字段时用 reserved 占位，防止后来者复用导致老客户端解析错误：

message OrderReply {
  reserved 7, 8;
  reserved "legacy_code", "internal_flag";

  string order_id = 1;
  string title = 2;
}

• 新增字段必须是可选语义，老客户端收到未知字段会忽略（proto3 保留未知字段），新客户端读到缺失字段得到默认值。
• 不要改字段类型。int32 改 string 会导致解析失败；确实需要时新增字段并逐步废弃旧字段。

与 REST 侧的兼容性规则不同：JSON 的字段名是契约，删字段会让老客户端拿到 null，改字段名等同于删除。若同时提供 gRPC 与 REST，应当让两者共用同一份语义模型，避免两套演进节奏。

序列化的整体策略（源生成、裁剪友好、性能取舍）见 序列化与 JSON 源生成 。

3. 双跑与灰度

一句话总结： 双跑是迁移的安全网：新老服务并行运行，用反向代理或特性开关逐步切流，任何异常都能秒级回退。

迁移最忌讳「一次性切换」。正确的路径是并行运行 + 渐进切流：

客户端 → 网关/代理 → [WCF 旧服务]
                  ↘ [gRPC/REST 新服务]

切流的三个层次，粒度由粗到细：

1. 按客户端切。先让内部工具切到新服务，观察一周再切外部客户端。
2. 按租户/用户切。用特性开关按比例放量，1% → 10% → 50% → 100%。
3. 按接口切。同一个服务里，先切读接口再切写接口，风险最低。

反向代理层实现灰度（以 YARP 为例）：

builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

builder.Services.AddSingleton<ITransformProvider, TenantRoutingTransform>();

public sealed class TenantRoutingTransform : ITransformProvider
{
    public void Apply(TransformBuilderContext context)
    {
        context.AddRequestTransform(async ctx =>
        {
            var tenant = ctx.HttpContext.Request.Headers["X-Tenant-Id"].ToString();
            var useNew = await _flags.IsEnabledAsync("new-order-service", tenant);

            ctx.ProxyRequest.RequestUri = useNew
                ? new Uri("http://orders-v2" + ctx.Path)
                : new Uri("http://orders-v1" + ctx.Path);
        });
    }
}

3.1 影子流量与结果比对

一句话总结： 影子流量把生产请求复制给新服务并比对结果，能在不影响用户的前提下发现语义差异，是迁移期最有效的验证手段。

灰度切流只能验证「新服务是否可用」，无法验证「新服务的结果是否与旧服务一致」。影子流量解决后者：把真实请求复制一份发给新服务，丢弃其响应，只记录与旧服务响应的差异。

app.Use(async (ctx, next) =>
{
    if (_shadow.ShouldShadow(ctx))
    {
        var body = await ReadBodyAsync(ctx.Request);
        _ = Task.Run(() => _shadow.SendAsync(ctx, body)); // 不阻塞主请求
    }
    await next();
});

比对要点：

• 只复制幂等的读请求。写请求的影子调用会产生副作用，需要专门的隔离环境。
• 归一化后再比对。字段顺序、时间精度、空值表示都可能不同，直接比 JSON 字符串会全是差异。
• 记录差异样本而非全量。差异率与若干典型样本足够定位问题。
• 影子流量要限速。生产峰值流量全部复制会给新服务与下游数据库带来额外压力。

影子流量的另一个价值是性能基线：能直接对比同一请求在新旧服务上的耗时分布，为容量规划提供依据。

4. 安全模型差异

一句话总结： WCF 的 WS-Security 在消息层做加密与签名，gRPC 与 REST 依赖传输层 TLS 加令牌认证，两者不是等价替换，需要重新设计信任边界。

这是迁移中最容易被低估的部分。WCF 的安全能力与 WS-* 深度绑定：

关键差异有四点：

第一，加密层次不同。WS-Security 在消息层加密，意味着消息经过中间节点（网关、队列）时依然保持加密。TLS 只保护传输段，网关解密后消息即明文。若合规要求「端到端加密」，必须改用应用层加密（如 JWE），而不能简单依赖 TLS。

第二，认证模型的粒度不同。WCF 的 ServiceSecurityContext.Current.PrimaryIdentity 提供调用者身份，配合 PrincipalPermission 做方法级授权。ASP.NET Core 用策略授权：

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("CanSubmitOrder", policy =>
        policy.RequireClaim("scope", "orders.write"));
});

app.MapPost("/orders", (SubmitOrderRequest req) => { /* ... */ })
   .RequireAuthorization("CanSubmitOrder");

第三，mTLS 的运维成本。若原系统用客户端证书认证，迁移后需要一套证书轮换机制（如 cert-manager 或 SPIFFE）。证书过期导致的批量调用失败是迁移后的高频事故，必须有到期告警。

第四，身份传播。WCF 的 Impersonation 能让服务以调用者身份访问下游资源，这在 Web 场景下不应延续——正确做法是服务用自己的身份访问下游，用调用者声明做授权决策。这是安全模型的根本转变，需要逐个接口重新审视。

关于认证、授权与身份体系在 .NET 中的完整落地，可参考 安全、认证与身份 。

4.1 证书与 mTLS 的运维细节

一句话总结： mTLS 把安全责任从框架转移到了运维，证书签发、轮换、吊销与到期监控必须自动化，否则会成为最隐蔽的故障源。

若原 WCF 系统使用客户端证书认证，迁移后需要一套完整的证书生命周期管理。手工管理在几十个服务、上百个客户端的规模下必然失控。

核心要求有四条：

1. 自动签发。用 cert-manager（Kubernetes）、SPIFFE/SPIRE 或企业内部 CA 自动签发，禁止手工生成证书。
2. 自动轮换。证书有效期应短（如 90 天）并自动续期。长期证书一旦泄露，影响面更大。
3. 到期监控。即使有自动轮换，也必须对「轮换失败」告警。证书到期的故障特征是突然的、全量的连接失败，没有降级过程。
4. 吊销机制。客户端失窃或下线时需要能吊销证书，CRL 或 OCSP 的可用性本身也要监控。

证书链的信任配置是另一个高频问题。客户端与服务端需要各自信任对方的 CA，若中间 CA 缺失，表现为「证书有效但握手失败」。排查时用 openssl s_client -connect host:443 -showcerts 打印完整链，逐级核对。

一个务实的替代方案是用令牌认证替代证书认证。若业务上并不严格要求双向认证，把客户端证书换成 OAuth2 的客户端凭证流程，运维复杂度会显著下降——令牌的签发、轮换与吊销由 IdP 统一处理，服务端只需验证 JWT 签名。

5. 客户端改造与回归

一句话总结： 客户端改造要优先解决超时、重试与会话语义的差异，回归验证必须覆盖异常路径而不只是正常路径。

客户端的改造点按优先级排列：

第一，超时语义。WCF 的 sendTimeout、receiveTimeout、closeTimeout 三个超时在 HTTP 时代合并为「请求超时」，且默认为 100 秒。迁移后必须显式设置，并区分连接超时与读取超时：

var channel = GrpcChannel.ForAddress("https://orders.internal", new GrpcChannelOptions
{
    HttpHandler = new SocketsHttpHandler
    {
        ConnectTimeout = TimeSpan.FromSeconds(3),
        PooledConnectionIdleTimeout = TimeSpan.FromMinutes(2),
    },
});

第二，重试语义。WCF 的 ReliableSession 提供有状态的重传保证，HTTP 没有等价物。迁移后需要显式配置重试策略，且必须保证幂等：

builder.Services.AddGrpcClient<OrderService.OrderServiceClient>(o =>
{
    o.Address = new Uri("https://orders.internal");
}).AddStandardResilienceHandler(options =>
{
    options.Retry.MaxRetryAttempts = 3;
    options.Retry.ShouldHandle = args => ValueTask.FromResult(
        args.Outcome.Result?.StatusCode is StatusCode.Unavailable);
});

第三，会话语义。SessionMode.Required 的 WCF 服务依赖会话关联，迁移到无状态的 gRPC 后需要显式传递会话标识（作为消息字段或元数据），并自行处理会话状态。

第四，单向操作。WCF 的 IsOneWay = true 语义是「发送即返回」，迁移后如果没有对应的异步机制，会退化成同步等待，导致客户端延迟上升。

第五，回调契约。DuplexChannelFactory 的客户端回调在 gRPC 中需要用双向流或独立的通知通道（SignalR）替代，这通常是改造量最大的部分。

回归验证的策略：

• 契约测试优先。用同一组输入分别调用新旧服务，比对响应。
• 异常路径必须覆盖。WCF 的 FaultException<T> 迁移后变成 RpcException 或 ProblemDetails，客户端的异常处理分支必须逐一验证。
• 边界值要测。日期时间、时区、decimal 精度、大整数、空字符串与 null，都是序列化差异的高发区。
• 性能回归。gRPC 通常比 SOAP 快，但 REST/JSON 在小消息上可能因序列化开销反而不如二进制编码的 WCF。

若迁移目标是 REST 而非 gRPC，端点组织与参数绑定的写法见 Web API 与 Minimal API ；接口演进与版本共存策略见 API 版本管理与 OpenAPI 。这两者在对外暴露的服务上尤其重要。

6. 常见坑与排错

一句话总结： 迁移期的问题集中在序列化差异、超时错配、安全配置遗漏与契约演进纪律四类，多数可以在测试环境用契约测试提前发现。

排错清单：

1. 日期时间偏移 → DateTime 的 Kind 在序列化中丢失，统一使用 DateTimeOffset 或 UTC 时间。
2. decimal 精度丢失 → JSON 用双精度浮点表示数字，金额必须序列化为字符串或使用 Protobuf 的 string 承载。
3. 枚举值错位 → 见 2.1，proto3 枚举必须有 UNSPECIFIED = 0。
4. 调用超时但服务端成功 → 客户端超时短于服务端处理时间，或重试叠加导致客户端已放弃，需对齐超时与重试参数。
5. 证书过期批量失败 → mTLS 证书轮换未自动化，加到期告警与自动续期。
6. 老客户端无法解析新响应 → 删除了 JSON 字段或复用了 Protobuf 字段编号，回退并改用新增字段的方式演进。
7. 大消息失败 → gRPC 默认消息上限 4MB，超出需调整 MaxReceiveMessageSize，或改用分页与流式传输。
8. 网关不支持 HTTP/2 → gRPC 需要端到端的 HTTP/2，路径上任何只支持 HTTP/1.1 的代理都会导致失败，需确认或改用 gRPC-Web。

其中第 8 条是最常见的「本地能跑、生产不行」原因。排查方法是逐跳验证协议：客户端 → 网关 → 负载均衡 → 服务，任一跳降级为 HTTP/1.1 就会失败。

7. 工程实践与迁移节奏

一句话总结： 迁移应按契约盘点、并行双跑、逐接口切流、清理旧服务的节奏推进，每一步都保留回退能力。

实践建议：

• 契约先行，先冻结再迁移。迁移期间禁止修改 WCF 契约，否则两边同时变化会让问题难以定位。
• 新旧服务共享领域逻辑。把业务逻辑抽到独立的类库，新旧服务都引用它，避免迁移期间出现两套实现导致行为漂移。
• 监控要区分新旧。在指标与日志中打标 implementation=wcf|grpc，才能对比切流前后的差异。
• 回退要演练。切流开关的回退路径必须在预发布环境演练过，否则事故时会发现开关失效。
• 清理要有时间表。双跑状态不宜长期存在，明确旧服务的下线日期并跟踪客户端迁移进度，否则会永久维护两套。

迁移的节奏可以概括为四步：盘点并冻结契约 → 实现新服务并影子验证 → 按客户端与接口逐步切流 → 确认无流量后下线旧服务。每一步的完成标准都应当是可观测的指标，而不是「感觉差不多了」。

7.1 迁移完成的判定标准

一句话总结： 旧服务下线的判据是「连续两周零真实流量」，而不是「新服务已上线」，两者之间往往隔着数月的客户端清理工作。

判断迁移是否真正完成，需要一组可验证的指标而非主观判断：

最后一条尤其容易被忽略。灰度开关在迁移完成后如果不清理，会长期留在代码里形成技术债，且每次重构都要考虑两个分支。开关的生命周期应当从引入时就有明确的移除计划。

契约收敛同样重要。迁移期为了兼容旧客户端，往往会在新契约里保留一些「临时」字段或宽松解析。这些妥协必须在下线旧客户端后清理，否则新契约会永久继承旧设计的包袱。

8. 总结

WCF 迁移的难点从来不是「把 SOAP 换成 gRPC」这个动作，而是那些在 WCF 里被框架隐式承担的语义：会话、事务、可靠传输、消息级安全。迁移的过程本质上是一次显式化——把这些隐式保证逐一识别出来，要么用新框架的对应能力替代，要么承认它不再需要。凡是跳过这一步、只做协议替换的项目，都会在切流后遇到「功能都对但行为不对」的疑难问题。

延伸阅读

• gRPC 与微服务通信
• API 版本管理与 OpenAPI