GreeterService 必须继承 GreeterBase 并重写返回 Task 的方法，否则客户端收到 StatusCode.Unimplemented 错误；.proto 文件需通过 Grpc.Tools 自动生成 GreeterBase 等类型，项目中配置 ；MapGrpcService 要在 UseRouting() 后、UseEndpoints() 前注册，且仅对 HTTP/2 有效；一元方法中应使用 ServerCallContext.CancellationToken 响应客户端取消；启用 options.EnableDetailedErrors = true（仅开发）才能让 RpcException.Detail 透传至客户端。
GreeterService 必须继承自 GreeterBase，且重写方法返回 Task<t></t> —— 否则客户端会收到 StatusCode.Unimplemented 错误，而不是你预期的业务逻辑。
怎么让 .proto 文件生成服务基类
关键不是手写，而是让 Grpc.Tools 在构建时自动产出：GreeterBase、HelloRequest、HelloReply 这些类型。
确保项目文件（.csproj）中包含正确配置的 <protobuf></protobuf> 项：
<ItemGroup> <Protobuf Include="Protos\greet.proto" GrpcServices="Server" /> </ItemGroup>
-
GrpcServices="Server"表示只生成服务端基类（GreeterBase），不生成客户端存根；若要同时支持调用其他服务，改用Both -
Include路径必须是相对于项目根目录的，且.proto文件需实际存在于该路径下（如Protos/greet.proto） - 不要手动把生成的
.cs文件加进项目——它们在obj/下临时存在，修改会被下次构建覆盖
为什么 MapGrpcService 不生效
常见原因是注册顺序或中间件冲突。ASP.NET Core 要求 gRPC 端点必须在 UseRouting() 之后、UseEndpoints() 或 UseAuthorization() 之前注册。
典型正确顺序如下：
app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); app.MapGrpcService<GreeterService>(); // 必须在这行 app.MapControllers();
- 如果用了
UseEndpoints，请确认没有遗漏endpoints.MapGrpcService<t>()</t>调用 -
MapGrpcService<t></t>仅对 HTTP/2 请求有效；开发时若用浏览器直接访问https://localhost:5001/greet.Greeter/SayHello，会失败——浏览器不支持 gRPC-Web 以外的原生 gRPC - 检查
Program.cs是否启用了 HTTP/2：Kestrel 默认只在 HTTPS 下启用 HTTP/2，HTTP 端口（如 5000）默认不支持
一元方法里怎么获取请求上下文和取消信号
ServerCallContext 不只是占位符，它提供真实可用的运行时信息，比如截止时间、客户端元数据、取消 CancellationToken。
例如，你想在超时前主动退出耗时操作：
public override async Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
{
using var cts = CancellationTokenSource.CreateLinkedTokenSource(context.CancellationToken);
cts.CancelAfter(TimeSpan.FromSeconds(3));
try
{
var result = await HeavyWorkAsync(cts.Token); // 传入组合后的 token
return new HelloReply { Message = $"Hello {request.Name} -> {result}" };
}
catch (OperationCanceledException)
{
throw new RpcException(new Status(StatusCode.DeadlineExceeded, "Processing timed out"));
}
}
-
context.CancellationToken是客户端发起的取消信号（比如移动端断网、前端主动 abort） - 不要直接 await
context.CancellationToken.WaitHandle，应传给支持CancellationToken的异步 API - 若忽略
context.CancellationToken，服务将无法响应客户端中断，造成连接堆积和资源泄漏
为什么客户端收不到错误详情
默认情况下，RpcException 的 Status.Detail 字段不会被序列化到 wire 上——除非你在服务器端显式启用详细错误模式。
仅限开发环境，在 Program.cs 中添加：
builder.Services.AddGrpc(options =>
{
options.EnableDetailedErrors = true; // ⚠️ 生产环境必须关掉
});
- 关闭后，客户端收到的
RpcException.Status仍包含StatusCode和简短消息，但Detail为空 - 生产环境若需结构化错误信息，应通过自定义状态码 + 响应体字段（如
error_code、debug_id）传递，而非依赖Status.Detail - 这个开关不影响
StatusCode.Unimplemented这类底层错误的传播——它们始终可见
ServerCallContext 和 GrpcServices 属性是两个最容易被跳过的细节：一个决定你能拿到什么运行时信息，另一个决定构建时生成哪些类型。漏掉任意一个，服务就只是“能编译”，而不是“能通信”。 
