以下是针对《工业上位机接口规范设计RESTful API JSON契约》的更多代码示例补充主要覆盖 .NET 8/9 时代最常见的几种实现方式以及实际工业项目中最常遇到的几种场景。我将按以下分类给出更详细、可直接复制粘贴的示例代码统一响应模型基类 泛型全局异常处理中间件控制器常用写法GET / PATCH / POST 带幂等参数校验 业务错误码OpenAPI 文档增强Swagger 配置幂等性中间件简单实现客户端调用示例Refit 接口定义1. 统一响应模型推荐做法// ResponseBase.cspublicabstractclassResponseBase{publicintCode{get;set;}0;publicstringMessage{get;set;}success;publicstringTraceId{get;set;}Activity.Current?.Id??Guid.NewGuid().ToString(N);publicDateTimeTimestamp{get;set;}DateTime.UtcNow;}// 成功响应publicclassApiResponseT:ResponseBase{publicT?Data{get;set;}publicstaticApiResponseTSuccess(Tdata)new(){Datadata};publicstaticApiResponseTSuccess()new();}// 失败响应publicclassApiErrorResponse:ResponseBase{publicListErrorDetail?Errors{get;set;}publicstaticApiErrorResponseFail(intcode,stringmessage,ListErrorDetail?errorsnull){returnnewApiErrorResponse{Codecode,Messagemessage,Errorserrors};}}publicclassErrorDetail{publicstring?Field{get;set;}publicstring?Reason{get;set;}publicobject?Value{get;set;}}2. 全局异常处理中间件推荐放在 Program.cs// ExceptionMiddleware.cspublicclassExceptionMiddleware{privatereadonlyRequestDelegate_next;privatereadonlyILoggerExceptionMiddleware_logger;publicExceptionMiddleware(RequestDelegatenext,ILoggerExceptionMiddlewarelogger){_nextnext;_loggerlogger;}publicasyncTaskInvokeAsync(HttpContextcontext){try{await_next(context);}catch(ValidationExceptionex)// FluentValidation{context.Response.StatusCodeStatusCodes.Status400BadRequest;varerrorsex.Errors.Select(enewErrorDetail{Fielde.PropertyName,Reasone.ErrorMessage,Valuee.AttemptedValue}).ToList();awaitcontext.Response.WriteAsJsonAsync(ApiErrorResponse.Fail(1001,参数校验失败,errors));}catch(BusinessExceptionex)// 自定义业务异常{context.Response.StatusCodeStatusCodes.Status400BadRequest;awaitcontext.Response.WriteAsJsonAsync(ApiErrorResponse.Fail(ex.Code,ex.Message));}catch(Exceptionex){_logger.LogError(ex,未处理的异常发生。TraceId: {TraceId},Activity.Current?.Id);context.Response.StatusCodeStatusCodes.Status500InternalServerError;awaitcontext.Response.WriteAsJsonAsync(ApiErrorResponse.Fail(9999,服务器内部错误请联系管理员));}}}// Program.cs 中使用app.UseMiddlewareExceptionMiddleware();3. 控制器常用写法示例[ApiController][Route(api/v{version:apiVersion}/[controller])][ApiVersion(1.0)]publicclassDevicesController:ControllerBase{privatereadonlyIDeviceService_deviceService;privatereadonlyIIdempotencyService_idempotencyService;publicDevicesController(IDeviceServicedeviceService,IIdempotencyServiceidempotencyService){_deviceServicedeviceService;_idempotencyServiceidempotencyService;}/// summary/// 获取单台设备实时状态/// /summary[HttpGet({deviceId}/status)][ProducesResponseType(typeof(ApiResponseDeviceStatusDto),200)][ProducesResponseType(typeof(ApiErrorResponse),400)]publicasyncTaskIActionResultGetStatus(stringdeviceId){varstatusawait_deviceService.GetDeviceStatusAsync(deviceId);returnOk(ApiResponseDeviceStatusDto.Success(status));}/// summary/// 局部更新设备参数幂等/// /summary[HttpPatch({deviceId}/parameters)][ProducesResponseType(204)][ProducesResponseType(typeof(ApiErrorResponse),400)]publicasyncTaskIActionResultUpdateParameters(stringdeviceId,[FromBody]UpdateDeviceParametersRequestrequest){await_deviceService.UpdateParametersAsync(deviceId,request);returnNoContent();}/// summary/// 下发生产指令带幂等键/// /summary[HttpPost(commands)][ProducesResponseType(typeof(ApiResponseCommandResult),200)][ProducesResponseType(typeof(ApiErrorResponse),400)]publicasyncTaskIActionResultIssueCommand([FromBody]IssueCommandRequestrequest){// 检查幂等键if(await_idempotencyService.ExistsAsync(request.IdempotencyKey)){varpreviousawait_idempotencyService.GetResultAsync(request.IdempotencyKey);returnOk(ApiResponseCommandResult.Success(previous));}varresultawait_deviceService.IssueCommandAsync(request);// 记录幂等结果建议异步 缓存/数据库await_idempotencyService.SaveResultAsync(request.IdempotencyKey,result,TimeSpan.FromDays(7));returnOk(ApiResponseCommandResult.Success(result));}}4. DTO 示例带 FluentValidation 校验publicclassUpdateDeviceParametersRequest{publicint?TargetSpeed{get;set;}publicbool?AutoMode{get;set;}publicstring?RecipeId{get;set;}}publicclassUpdateDeviceParametersRequestValidator:AbstractValidatorUpdateDeviceParametersRequest{publicUpdateDeviceParametersRequestValidator(){RuleFor(xx.TargetSpeed).InclusiveBetween(800,3000).When(xx.TargetSpeed.HasValue).WithMessage(目标速度必须在800-3000之间);RuleFor(xx.RecipeId).MaximumLength(50).When(x!string.IsNullOrEmpty(x.RecipeId));}}5. Swagger / OpenAPI 配置增强Program.csbuilder.Services.AddSwaggerGen(c{c.SwaggerDoc(v1,newOpenApiInfo{Title工业上位机 REST API,Versionv1.0,Description工业现场上位机标准接口RESTful JSON契约});// 支持 ApiVersionc.OperationFilterAddApiVersionHeader();// JWT 示例c.AddSecurityDefinition(Bearer,newOpenApiSecurityScheme{InParameterLocation.Header,Description请输入 Bearer Token,NameAuthorization,TypeSecuritySchemeType.ApiKey,SchemeBearer});c.AddSecurityRequirement(newOpenApiSecurityRequirement{{newOpenApiSecurityScheme{ReferencenewOpenApiReference{TypeReferenceType.SecurityScheme,IdBearer}},Array.Emptystring()}});});6. 简单幂等中间件可选适合轻量项目publicclassIdempotencyMiddleware{privatereadonlyRequestDelegate_next;privatereadonlyIIdempotencyService_idempotencyService;publicIdempotencyMiddleware(RequestDelegatenext,IIdempotencyServiceidempotencyService){_nextnext;_idempotencyServiceidempotencyService;}publicasyncTaskInvokeAsync(HttpContextcontext){if(context.Request.MethodHttpMethods.Postcontext.Request.Headers.TryGetValue(Idempotency-Key,outvaridempotencyKeyValues)){varkeyidempotencyKeyValues.FirstOrDefault();if(!string.IsNullOrEmpty(key)await_idempotencyService.ExistsAsync(key)){varresultawait_idempotencyService.GetResultAsync(key);context.Response.StatusCodeStatusCodes.Status200OK;awaitcontext.Response.WriteAsJsonAsync(result);return;}}await_next(context);}}7. 客户端调用示例Refit 接口定义publicinterfaceIDeviceApiClient{[Get(/api/v1/devices/{deviceId}/status)]TaskApiResponseDeviceStatusDtoGetDeviceStatus(stringdeviceId);[Patch(/api/v1/devices/{deviceId}/parameters)]TaskUpdateParameters(stringdeviceId,[Body]UpdateDeviceParametersRequestrequest);[Post(/api/v1/production/commands)][Headers(Idempotency-Key: {idempotencyKey})]TaskApiResponseCommandResultIssueCommand(stringidempotencyKey,[Body]IssueCommandRequestrequest);}这些代码示例覆盖了目前工业上位机项目中最常见的 80% 场景。如果你需要某个具体接口的完整 Controller Service DTO Validator 组合或者想看 Golang / Python / Java 的对应实现也可以继续告诉我我可以继续补充。