{"id":122586,"date":"2026-11-05T08:09:14","date_gmt":"2026-11-05T00:09:14","guid":{"rendered":"https:\/\/www.wsisp.com\/helps\/122586.html"},"modified":"2026-11-05T08:09:14","modified_gmt":"2026-11-05T00:09:14","slug":"%e5%b7%a5%e4%b8%9a%e4%b8%8a%e4%bd%8d%e6%9c%ba%e6%8e%a5%e5%8f%a3%e8%a7%84%e8%8c%83%e8%ae%be%e8%ae%a1%ef%bc%9arestful-api-json%e5%a5%91%e7%ba%a6","status":"publish","type":"post","link":"https:\/\/www.wsisp.com\/helps\/122586.html","title":{"rendered":"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6"},"content":{"rendered":"

\u4ee5\u4e0b\u662f\u9488\u5bf9\u300a\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1：RESTful API + JSON\u5951\u7ea6\u300b\u7684\u66f4\u591a\u4ee3\u7801\u793a\u4f8b\u8865\u5145，\u4e3b\u8981\u8986\u76d6 .NET 8\/9 \u65f6\u4ee3\u6700\u5e38\u89c1\u7684\u51e0\u79cd\u5b9e\u73b0\u65b9\u5f0f，\u4ee5\u53ca\u5b9e\u9645\u5de5\u4e1a\u9879\u76ee\u4e2d\u6700\u5e38\u9047\u5230\u7684\u51e0\u79cd\u573a\u666f\u3002<\/p>\n

\u6211\u5c06\u6309\u4ee5\u4e0b\u5206\u7c7b\u7ed9\u51fa\u66f4\u8be6\u7ec6\u3001\u53ef\u76f4\u63a5\u590d\u5236\u7c98\u8d34\u7684\u793a\u4f8b\u4ee3\u7801：<\/p>\n

  • \u7edf\u4e00\u54cd\u5e94\u6a21\u578b（\u57fa\u7c7b + \u6cdb\u578b）<\/li>\n
  • \u5168\u5c40\u5f02\u5e38\u5904\u7406\u4e2d\u95f4\u4ef6<\/li>\n
  • \u63a7\u5236\u5668\u5e38\u7528\u5199\u6cd5（GET \/ PATCH \/ POST \u5e26\u5e42\u7b49）<\/li>\n
  • \u53c2\u6570\u6821\u9a8c + \u4e1a\u52a1\u9519\u8bef\u7801<\/li>\n
  • OpenAPI \u6587\u6863\u589e\u5f3a（Swagger \u914d\u7f6e）<\/li>\n
  • \u5e42\u7b49\u6027\u4e2d\u95f4\u4ef6（\u7b80\u5355\u5b9e\u73b0）<\/li>\n
  • \u5ba2\u6237\u7aef\u8c03\u7528\u793a\u4f8b（Refit \u63a5\u53e3\u5b9a\u4e49）<\/li>\n

    1. \u7edf\u4e00\u54cd\u5e94\u6a21\u578b（\u63a8\u8350\u505a\u6cd5）<\/h4>\n

    \/\/ ResponseBase.cs<\/span>
    \npublic<\/span> abstract<\/span> class<\/span> ResponseBase<\/span>
    \n{<\/span>
    \n public<\/span> int<\/span><\/span> Code {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span> =<\/span> 0<\/span>;<\/span>
    \n public<\/span> string<\/span><\/span> Message {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span> =<\/span> "success"<\/span>;<\/span>
    \n public<\/span> string<\/span><\/span> TraceId {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span> =<\/span> Activity.<\/span>Current?.<\/span>Id ??<\/span> Guid.<\/span>NewGuid<\/span>(<\/span>)<\/span>.<\/span>ToString<\/span>(<\/span>"N"<\/span>)<\/span>;<\/span>
    \n public<\/span> DateTime<\/span> Timestamp {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span> =<\/span> DateTime.<\/span>UtcNow;<\/span>
    \n}<\/span><\/p>\n

    \/\/ \u6210\u529f\u54cd\u5e94<\/span>
    \npublic<\/span> class<\/span> ApiResponse<<\/span>T><\/span><\/span> :<\/span> ResponseBase<\/span><\/span>
    \n{<\/span>
    \n public<\/span> T?<\/span><\/span> Data {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span><\/p>\n

    public<\/span> static<\/span> ApiResponse<<\/span>T><\/span><\/span> Success<\/span>(<\/span>T<\/span> data)<\/span> =><\/span> new<\/span>(<\/span>)<\/span> {<\/span> Data =<\/span> data }<\/span>;<\/span>
    \n public<\/span> static<\/span> ApiResponse<<\/span>T><\/span><\/span> Success<\/span>(<\/span>)<\/span> =><\/span> new<\/span>(<\/span>)<\/span>;<\/span>
    \n}<\/span><\/p>\n

    \/\/ \u5931\u8d25\u54cd\u5e94<\/span>
    \npublic<\/span> class<\/span> ApiErrorResponse<\/span> :<\/span> ResponseBase<\/span><\/span>
    \n{<\/span>
    \n public<\/span> List<<\/span>ErrorDetail><\/span>?<\/span><\/span> Errors {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span><\/p>\n

    public<\/span> static<\/span> ApiErrorResponse<\/span> Fail<\/span>(<\/span>int<\/span><\/span> code,<\/span> string<\/span><\/span> message,<\/span> List<<\/span>ErrorDetail><\/span>?<\/span><\/span> errors =<\/span> null<\/span>)<\/span>
    \n {<\/span>
    \n return<\/span> new<\/span> ApiErrorResponse<\/span>
    \n {<\/span>
    \n Code =<\/span> code,<\/span>
    \n Message =<\/span> message,<\/span>
    \n Errors =<\/span> errors
    \n }<\/span>;<\/span>
    \n }<\/span>
    \n}<\/span><\/p>\n

    public<\/span> class<\/span> ErrorDetail<\/span>
    \n{<\/span>
    \n public<\/span> string<\/span>?<\/span><\/span> Field {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span>
    \n public<\/span> string<\/span>?<\/span><\/span> Reason {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span>
    \n public<\/span> object<\/span>?<\/span><\/span> Value {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span>
    \n}<\/span><\/p>\n

    2. \u5168\u5c40\u5f02\u5e38\u5904\u7406\u4e2d\u95f4\u4ef6（\u63a8\u8350\u653e\u5728 Program.cs）<\/h4>\n

    \/\/ ExceptionMiddleware.cs<\/span>
    \npublic<\/span> class<\/span> ExceptionMiddleware<\/span>
    \n{<\/span>
    \n private<\/span> readonly<\/span> RequestDelegate<\/span> _next;<\/span>
    \n private<\/span> readonly<\/span> ILogger<<\/span>ExceptionMiddleware><\/span><\/span> _logger;<\/span><\/p>\n

    public<\/span> ExceptionMiddleware<\/span>(<\/span>RequestDelegate<\/span> next,<\/span> ILogger<<\/span>ExceptionMiddleware><\/span><\/span> logger)<\/span>
    \n {<\/span>
    \n _next =<\/span> next;<\/span>
    \n _logger =<\/span> logger;<\/span>
    \n }<\/span><\/p>\n

    public<\/span> async<\/span> Task<\/span> InvokeAsync<\/span>(<\/span>HttpContext<\/span> context)<\/span>
    \n {<\/span>
    \n try<\/span>
    \n {<\/span>
    \n await<\/span> _next<\/span>(<\/span>context)<\/span>;<\/span>
    \n }<\/span>
    \n catch<\/span> (<\/span>ValidationException<\/span> ex)<\/span> \/\/ FluentValidation<\/span>
    \n {<\/span>
    \n context.<\/span>Response.<\/span>StatusCode =<\/span> StatusCodes.<\/span>Status400BadRequest;<\/span>
    \n var<\/span><\/span> errors =<\/span> ex.<\/span>Errors.<\/span>Select<\/span>(<\/span>e =><\/span> new<\/span> ErrorDetail<\/span>
    \n {<\/span>
    \n Field =<\/span> e.<\/span>PropertyName,<\/span>
    \n Reason =<\/span> e.<\/span>ErrorMessage,<\/span>
    \n Value =<\/span> e.<\/span>AttemptedValue
    \n }<\/span>)<\/span>.<\/span>ToList<\/span>(<\/span>)<\/span>;<\/span><\/p>\n

    await<\/span> context.<\/span>Response.<\/span>WriteAsJsonAsync<\/span>(<\/span>ApiErrorResponse.<\/span>Fail<\/span>(<\/span>1001<\/span>,<\/span> "\u53c2\u6570\u6821\u9a8c\u5931\u8d25"<\/span>,<\/span> errors)<\/span>)<\/span>;<\/span>
    \n }<\/span>
    \n catch<\/span> (<\/span>BusinessException<\/span> ex)<\/span> \/\/ \u81ea\u5b9a\u4e49\u4e1a\u52a1\u5f02\u5e38<\/span>
    \n {<\/span>
    \n context.<\/span>Response.<\/span>StatusCode =<\/span> StatusCodes.<\/span>Status400BadRequest;<\/span>
    \n await<\/span> context.<\/span>Response.<\/span>WriteAsJsonAsync<\/span>(<\/span>ApiErrorResponse.<\/span>Fail<\/span>(<\/span>ex.<\/span>Code,<\/span> ex.<\/span>Message)<\/span>)<\/span>;<\/span>
    \n }<\/span>
    \n catch<\/span> (<\/span>Exception<\/span> ex)<\/span>
    \n {<\/span>
    \n _logger.<\/span>LogError<\/span>(<\/span>ex,<\/span> "\u672a\u5904\u7406\u7684\u5f02\u5e38\u53d1\u751f\u3002TraceId: {TraceId}"<\/span>,<\/span> Activity.<\/span>Current?.<\/span>Id)<\/span>;<\/span>
    \n context.<\/span>Response.<\/span>StatusCode =<\/span> StatusCodes.<\/span>Status500InternalServerError;<\/span>
    \n await<\/span> context.<\/span>Response.<\/span>WriteAsJsonAsync<\/span>(<\/span>ApiErrorResponse.<\/span>Fail<\/span>(<\/span>9999<\/span>,<\/span> "\u670d\u52a1\u5668\u5185\u90e8\u9519\u8bef，\u8bf7\u8054\u7cfb\u7ba1\u7406\u5458"<\/span>)<\/span>)<\/span>;<\/span>
    \n }<\/span>
    \n }<\/span>
    \n}<\/span><\/p>\n

    \/\/ Program.cs \u4e2d\u4f7f\u7528<\/span>
    \napp.<\/span>UseMiddleware<\/span><<\/span>ExceptionMiddleware><\/span><\/span><\/span>(<\/span>)<\/span>;<\/span><\/p>\n

    3. \u63a7\u5236\u5668\u5e38\u7528\u5199\u6cd5\u793a\u4f8b<\/h4>\n

    [<\/span>ApiController<\/span><\/span>]<\/span>
    \n[<\/span>Route<\/span>(<\/span>"api\/v{version:apiVersion}\/[controller]"<\/span>)<\/span><\/span><\/span>]<\/span>
    \n[<\/span>ApiVersion<\/span>(<\/span>"1.0"<\/span>)<\/span><\/span><\/span>]<\/span>
    \npublic<\/span> class<\/span> DevicesController<\/span> :<\/span> ControllerBase<\/span><\/span>
    \n{<\/span>
    \n private<\/span> readonly<\/span> IDeviceService<\/span> _deviceService;<\/span>
    \n private<\/span> readonly<\/span> IIdempotencyService<\/span> _idempotencyService;<\/span><\/p>\n

    public<\/span> DevicesController<\/span>(<\/span>IDeviceService<\/span> deviceService,<\/span> IIdempotencyService<\/span> idempotencyService)<\/span>
    \n {<\/span>
    \n _deviceService =<\/span> deviceService;<\/span>
    \n _idempotencyService =<\/span> idempotencyService;<\/span>
    \n }<\/span><\/p>\n

    \/\/\/ <summary><\/span>
    \n \/\/\/ \u83b7\u53d6\u5355\u53f0\u8bbe\u5907\u5b9e\u65f6\u72b6\u6001<\/span>
    \n \/\/\/ <\/summary><\/span>
    \n [<\/span>HttpGet<\/span>(<\/span>"{deviceId}\/status"<\/span>)<\/span>]<\/span>
    \n [<\/span>ProducesResponseType<\/span>(<\/span>typeof<\/span>(<\/span>ApiResponse<<\/span>DeviceStatusDto><\/span><\/span>)<\/span>,<\/span> 200<\/span>)<\/span><\/span><\/span>]<\/span>
    \n [<\/span>ProducesResponseType<\/span>(<\/span>typeof<\/span>(<\/span>ApiErrorResponse<\/span>)<\/span>,<\/span> 400<\/span>)<\/span><\/span><\/span>]<\/span>
    \n public<\/span> async<\/span> Task<<\/span>IActionResult><\/span><\/span> GetStatus<\/span>(<\/span>string<\/span><\/span> deviceId)<\/span>
    \n {<\/span>
    \n var<\/span><\/span> status =<\/span> await<\/span> _deviceService.<\/span>GetDeviceStatusAsync<\/span>(<\/span>deviceId)<\/span>;<\/span>
    \n return<\/span> Ok<\/span>(<\/span>ApiResponse<<\/span>DeviceStatusDto><\/span>.<\/span>Success<\/span>(<\/span>status)<\/span>)<\/span>;<\/span>
    \n }<\/span><\/p>\n

    \/\/\/ <summary><\/span>
    \n \/\/\/ \u5c40\u90e8\u66f4\u65b0\u8bbe\u5907\u53c2\u6570（\u5e42\u7b49）<\/span>
    \n \/\/\/ <\/summary><\/span>
    \n [<\/span>HttpPatch<\/span>(<\/span>"{deviceId}\/parameters"<\/span>)<\/span>]<\/span>
    \n [<\/span>ProducesResponseType<\/span>(<\/span>204<\/span>)<\/span><\/span><\/span>]<\/span>
    \n [<\/span>ProducesResponseType<\/span>(<\/span>typeof<\/span>(<\/span>ApiErrorResponse<\/span>)<\/span>,<\/span> 400<\/span>)<\/span><\/span><\/span>]<\/span>
    \n public<\/span> async<\/span> Task<<\/span>IActionResult><\/span><\/span> UpdateParameters<\/span>(<\/span>string<\/span><\/span> deviceId,<\/span> [<\/span>FromBody<\/span><\/span>]<\/span> UpdateDeviceParametersRequest<\/span> request)<\/span>
    \n {<\/span>
    \n await<\/span> _deviceService.<\/span>UpdateParametersAsync<\/span>(<\/span>deviceId,<\/span> request)<\/span>;<\/span>
    \n return<\/span> NoContent<\/span>(<\/span>)<\/span>;<\/span>
    \n }<\/span><\/p>\n

    \/\/\/ <summary><\/span>
    \n \/\/\/ \u4e0b\u53d1\u751f\u4ea7\u6307\u4ee4（\u5e26\u5e42\u7b49\u952e）<\/span>
    \n \/\/\/ <\/summary><\/span>
    \n [<\/span>HttpPost<\/span>(<\/span>"commands"<\/span>)<\/span>]<\/span>
    \n [<\/span>ProducesResponseType<\/span>(<\/span>typeof<\/span>(<\/span>ApiResponse<<\/span>CommandResult><\/span><\/span>)<\/span>,<\/span> 200<\/span>)<\/span><\/span><\/span>]<\/span>
    \n [<\/span>ProducesResponseType<\/span>(<\/span>typeof<\/span>(<\/span>ApiErrorResponse<\/span>)<\/span>,<\/span> 400<\/span>)<\/span><\/span><\/span>]<\/span>
    \n public<\/span> async<\/span> Task<<\/span>IActionResult><\/span><\/span> IssueCommand<\/span>(<\/span>[<\/span>FromBody<\/span><\/span>]<\/span> IssueCommandRequest<\/span> request)<\/span>
    \n {<\/span>
    \n \/\/ \u68c0\u67e5\u5e42\u7b49\u952e<\/span>
    \n if<\/span> (<\/span>await<\/span> _idempotencyService.<\/span>ExistsAsync<\/span>(<\/span>request.<\/span>IdempotencyKey)<\/span>)<\/span>
    \n {<\/span>
    \n var<\/span><\/span> previous =<\/span> await<\/span> _idempotencyService.<\/span>GetResultAsync<\/span>(<\/span>request.<\/span>IdempotencyKey)<\/span>;<\/span>
    \n return<\/span> Ok<\/span>(<\/span>ApiResponse<<\/span>CommandResult><\/span>.<\/span>Success<\/span>(<\/span>previous)<\/span>)<\/span>;<\/span>
    \n }<\/span><\/p>\n

    var<\/span><\/span> result =<\/span> await<\/span> _deviceService.<\/span>IssueCommandAsync<\/span>(<\/span>request)<\/span>;<\/span><\/p>\n

    \/\/ \u8bb0\u5f55\u5e42\u7b49\u7ed3\u679c（\u5efa\u8bae\u5f02\u6b65 + \u7f13\u5b58\/\u6570\u636e\u5e93）<\/span>
    \n await<\/span> _idempotencyService.<\/span>SaveResultAsync<\/span>(<\/span>request.<\/span>IdempotencyKey,<\/span> result,<\/span> TimeSpan.<\/span>FromDays<\/span>(<\/span>7<\/span>)<\/span>)<\/span>;<\/span><\/p>\n

    return<\/span> Ok<\/span>(<\/span>ApiResponse<<\/span>CommandResult><\/span>.<\/span>Success<\/span>(<\/span>result)<\/span>)<\/span>;<\/span>
    \n }<\/span>
    \n}<\/span><\/p>\n

    4. DTO \u793a\u4f8b（\u5e26 FluentValidation \u6821\u9a8c）<\/h4>\n

    public<\/span> class<\/span> UpdateDeviceParametersRequest<\/span>
    \n{<\/span>
    \n public<\/span> int<\/span>?<\/span><\/span> TargetSpeed {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span>
    \n public<\/span> bool<\/span>?<\/span><\/span> AutoMode {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span>
    \n public<\/span> string<\/span>?<\/span><\/span> RecipeId {<\/span> get<\/span>;<\/span> set<\/span>;<\/span> }<\/span>
    \n}<\/span><\/p>\n

    public<\/span> class<\/span> UpdateDeviceParametersRequestValidator<\/span> :<\/span> AbstractValidator<<\/span>UpdateDeviceParametersRequest><\/span><\/span><\/span>
    \n{<\/span>
    \n public<\/span> UpdateDeviceParametersRequestValidator<\/span>(<\/span>)<\/span>
    \n {<\/span>
    \n RuleFor<\/span>(<\/span>x =><\/span> x.<\/span>TargetSpeed)<\/span>
    \n .<\/span>InclusiveBetween<\/span>(<\/span>800<\/span>,<\/span> 3000<\/span>)<\/span>.<\/span>When<\/span>(<\/span>x =><\/span> x.<\/span>TargetSpeed.<\/span>HasValue)<\/span>
    \n .<\/span>WithMessage<\/span>(<\/span>"\u76ee\u6807\u901f\u5ea6\u5fc5\u987b\u5728800-3000\u4e4b\u95f4"<\/span>)<\/span>;<\/span><\/p>\n

    RuleFor<\/span>(<\/span>x =><\/span> x.<\/span>RecipeId)<\/span>
    \n .<\/span>MaximumLength<\/span>(<\/span>50<\/span>)<\/span>.<\/span>When<\/span>(<\/span>x =><\/span> !<\/span>string<\/span>.<\/span>IsNullOrEmpty<\/span>(<\/span>x.<\/span>RecipeId)<\/span>)<\/span>;<\/span>
    \n }<\/span>
    \n}<\/span><\/p>\n

    5. Swagger \/ OpenAPI \u914d\u7f6e\u589e\u5f3a（Program.cs）<\/h4>\n

    builder.<\/span>Services.<\/span>AddSwaggerGen<\/span>(<\/span>c =><\/span>
    \n{<\/span>
    \n c.<\/span>SwaggerDoc<\/span>(<\/span>"v1"<\/span>,<\/span> new<\/span> OpenApiInfo<\/span>
    \n {<\/span>
    \n Title =<\/span> "\u5de5\u4e1a\u4e0a\u4f4d\u673a REST API"<\/span>,<\/span>
    \n Version =<\/span> "v1.0"<\/span>,<\/span>
    \n Description =<\/span> "\u5de5\u4e1a\u73b0\u573a\u4e0a\u4f4d\u673a\u6807\u51c6\u63a5\u53e3（RESTful + JSON\u5951\u7ea6）"<\/span>
    \n }<\/span>)<\/span>;<\/span><\/p>\n

    \/\/ \u652f\u6301 ApiVersion<\/span>
    \n c.<\/span>OperationFilter<\/span><<\/span>AddApiVersionHeader><\/span><\/span><\/span>(<\/span>)<\/span>;<\/span><\/p>\n

    \/\/ JWT \u793a\u4f8b<\/span>
    \n c.<\/span>AddSecurityDefinition<\/span>(<\/span>"Bearer"<\/span>,<\/span> new<\/span> OpenApiSecurityScheme<\/span>
    \n {<\/span>
    \n In =<\/span> ParameterLocation.<\/span>Header,<\/span>
    \n Description =<\/span> "\u8bf7\u8f93\u5165 Bearer Token"<\/span>,<\/span>
    \n Name =<\/span> "Authorization"<\/span>,<\/span>
    \n Type =<\/span> SecuritySchemeType.<\/span>ApiKey,<\/span>
    \n Scheme =<\/span> "Bearer"<\/span>
    \n }<\/span>)<\/span>;<\/span><\/p>\n

    c.<\/span>AddSecurityRequirement<\/span>(<\/span>new<\/span> OpenApiSecurityRequirement<\/span>
    \n {<\/span>
    \n {<\/span>
    \n new<\/span> OpenApiSecurityScheme<\/span>
    \n {<\/span>
    \n Reference =<\/span> new<\/span> OpenApiReference<\/span> {<\/span> Type =<\/span> ReferenceType.<\/span>SecurityScheme,<\/span> Id =<\/span> "Bearer"<\/span> }<\/span>
    \n }<\/span>,<\/span>
    \n Array.<\/span>Empty<\/span><<\/span>string<\/span>><\/span><\/span><\/span>(<\/span>)<\/span>
    \n }<\/span>
    \n }<\/span>)<\/span>;<\/span>
    \n}<\/span>)<\/span>;<\/span><\/p>\n

    6. \u7b80\u5355\u5e42\u7b49\u4e2d\u95f4\u4ef6（\u53ef\u9009，\u9002\u5408\u8f7b\u91cf\u9879\u76ee）<\/h4>\n

    public<\/span> class<\/span> IdempotencyMiddleware<\/span>
    \n{<\/span>
    \n private<\/span> readonly<\/span> RequestDelegate<\/span> _next;<\/span>
    \n private<\/span> readonly<\/span> IIdempotencyService<\/span> _idempotencyService;<\/span><\/p>\n

    public<\/span> IdempotencyMiddleware<\/span>(<\/span>RequestDelegate<\/span> next,<\/span> IIdempotencyService<\/span> idempotencyService)<\/span>
    \n {<\/span>
    \n _next =<\/span> next;<\/span>
    \n _idempotencyService =<\/span> idempotencyService;<\/span>
    \n }<\/span><\/p>\n

    public<\/span> async<\/span> Task<\/span> InvokeAsync<\/span>(<\/span>HttpContext<\/span> context)<\/span>
    \n {<\/span>
    \n if<\/span> (<\/span>context.<\/span>Request.<\/span>Method ==<\/span> HttpMethods.<\/span>Post &&<\/span>
    \n context.<\/span>Request.<\/span>Headers.<\/span>TryGetValue<\/span>(<\/span>"Idempotency-Key"<\/span>,<\/span> out<\/span> var<\/span><\/span> idempotencyKeyValues)<\/span>)<\/span>
    \n {<\/span>
    \n var<\/span><\/span> key =<\/span> idempotencyKeyValues.<\/span>FirstOrDefault<\/span>(<\/span>)<\/span>;<\/span>
    \n if<\/span> (<\/span>!<\/span>string<\/span>.<\/span>IsNullOrEmpty<\/span>(<\/span>key)<\/span> &&<\/span> await<\/span> _idempotencyService.<\/span>ExistsAsync<\/span>(<\/span>key)<\/span>)<\/span>
    \n {<\/span>
    \n var<\/span><\/span> result =<\/span> await<\/span> _idempotencyService.<\/span>GetResultAsync<\/span>(<\/span>key)<\/span>;<\/span>
    \n context.<\/span>Response.<\/span>StatusCode =<\/span> StatusCodes.<\/span>Status200OK;<\/span>
    \n await<\/span> context.<\/span>Response.<\/span>WriteAsJsonAsync<\/span>(<\/span>result)<\/span>;<\/span>
    \n return<\/span>;<\/span>
    \n }<\/span>
    \n }<\/span><\/p>\n

    await<\/span> _next<\/span>(<\/span>context)<\/span>;<\/span>
    \n }<\/span>
    \n}<\/span><\/p>\n

    7. \u5ba2\u6237\u7aef\u8c03\u7528\u793a\u4f8b（Refit \u63a5\u53e3\u5b9a\u4e49）<\/h4>\n

    public<\/span> interface<\/span> IDeviceApiClient<\/span>
    \n{<\/span>
    \n [<\/span>Get<\/span>(<\/span>"\/api\/v1\/devices\/{deviceId}\/status"<\/span>)<\/span><\/span><\/span>]<\/span>
    \n Task<<\/span>ApiResponse<<\/span>DeviceStatusDto><\/span>><\/span><\/span> GetDeviceStatus<\/span>(<\/span>string<\/span><\/span> deviceId)<\/span>;<\/span><\/p>\n

    [<\/span>Patch<\/span>(<\/span>"\/api\/v1\/devices\/{deviceId}\/parameters"<\/span>)<\/span><\/span><\/span>]<\/span>
    \n Task<\/span> UpdateParameters<\/span>(<\/span>string<\/span><\/span> deviceId,<\/span> [<\/span>Body<\/span><\/span>]<\/span> UpdateDeviceParametersRequest<\/span> request)<\/span>;<\/span><\/p>\n

    [<\/span>Post<\/span>(<\/span>"\/api\/v1\/production\/commands"<\/span>)<\/span><\/span><\/span>]<\/span>
    \n [<\/span>Headers<\/span>(<\/span>"Idempotency-Key: {idempotencyKey}"<\/span>)<\/span><\/span><\/span>]<\/span>
    \n Task<<\/span>ApiResponse<<\/span>CommandResult><\/span>><\/span><\/span> IssueCommand<\/span>(<\/span>string<\/span><\/span> idempotencyKey,<\/span> [<\/span>Body<\/span><\/span>]<\/span> IssueCommandRequest<\/span> request)<\/span>;<\/span>
    \n}<\/span><\/p>\n

    \u8fd9\u4e9b\u4ee3\u7801\u793a\u4f8b\u8986\u76d6\u4e86\u76ee\u524d\u5de5\u4e1a\u4e0a\u4f4d\u673a\u9879\u76ee\u4e2d\u6700\u5e38\u89c1\u7684 80% \u573a\u666f\u3002\u5982\u679c\u4f60\u9700\u8981\u67d0\u4e2a\u5177\u4f53\u63a5\u53e3\u7684\u5b8c\u6574 Controller + Service + DTO + Validator \u7ec4\u5408，\u6216\u8005\u60f3\u770b Golang \/ Python \/ Java \u7684\u5bf9\u5e94\u5b9e\u73b0，\u4e5f\u53ef\u4ee5\u7ee7\u7eed\u544a\u8bc9\u6211，\u6211\u53ef\u4ee5\u7ee7\u7eed\u8865\u5145\u3002<\/p>\n","protected":false},"excerpt":{"rendered":"

    \u4ee5\u4e0b\u662f\u9488\u5bf9\u300a\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1：RESTful API JSON\u5951\u7ea6\u300b\u7684\u66f4\u591a\u4ee3\u7801\u793a\u4f8b\u8865\u5145，\u4e3b\u8981\u8986\u76d6 .NET 8\/9 \u65f6\u4ee3\u6700\u5e38\u89c1\u7684\u51e0\u79cd\u5b9e\u73b0\u65b9\u5f0f，\u4ee5\u53ca\u5b9e\u9645\u5de5\u4e1a\u9879\u76ee\u4e2d\u6700\u5e38\u9047\u5230\u7684\u51e0\u79cd\u573a\u666f\u3002
    \n\u6211\u5c06\u6309\u4ee5\u4e0b\u5206\u7c7b\u7ed9\u51fa\u66f4\u8be6\u7ec6\u3001\u53ef\u76f4\u63a5\u590d\u5236\u7c98\u8d34\u7684\u793a\u4f8b\u4ee3\u7801：
    \n\u7edf\u4e00\u54cd\u5e94\u6a21\u578b（\u57fa\u7c7b \u6cdb\u578b）\u5168\u5c40\u5f02\u5e38\u5904\u7406\u4e2d\u95f4\u4ef6\u63a7\u5236\u5668\u5e38\u7528\u5199\u6cd5（GET \/ PATCH \/ POST \u5e26\u5e42\u7b49）\u53c2\u6570\u6821\u9a8c \u4e1a\u52a1<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[93,3440,292],"topic":[],"class_list":["post-122586","post","type-post","status-publish","format-standard","hentry","category-server","tag-json","tag-restful","tag-292"],"yoast_head":"\n\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.wsisp.com\/helps\/122586.html\" \/>\n<meta property=\"og:locale\" content=\"zh_CN\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\" \/>\n<meta property=\"og:description\" content=\"\u4ee5\u4e0b\u662f\u9488\u5bf9\u300a\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1：RESTful API JSON\u5951\u7ea6\u300b\u7684\u66f4\u591a\u4ee3\u7801\u793a\u4f8b\u8865\u5145，\u4e3b\u8981\u8986\u76d6 .NET 8\/9 \u65f6\u4ee3\u6700\u5e38\u89c1\u7684\u51e0\u79cd\u5b9e\u73b0\u65b9\u5f0f，\u4ee5\u53ca\u5b9e\u9645\u5de5\u4e1a\u9879\u76ee\u4e2d\u6700\u5e38\u9047\u5230\u7684\u51e0\u79cd\u573a\u666f\u3002 \u6211\u5c06\u6309\u4ee5\u4e0b\u5206\u7c7b\u7ed9\u51fa\u66f4\u8be6\u7ec6\u3001\u53ef\u76f4\u63a5\u590d\u5236\u7c98\u8d34\u7684\u793a\u4f8b\u4ee3\u7801： \u7edf\u4e00\u54cd\u5e94\u6a21\u578b（\u57fa\u7c7b \u6cdb\u578b）\u5168\u5c40\u5f02\u5e38\u5904\u7406\u4e2d\u95f4\u4ef6\u63a7\u5236\u5668\u5e38\u7528\u5199\u6cd5（GET \/ PATCH \/ POST \u5e26\u5e42\u7b49）\u53c2\u6570\u6821\u9a8c \u4e1a\u52a1\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.wsisp.com\/helps\/122586.html\" \/>\n<meta property=\"og:site_name\" content=\"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\" \/>\n<meta property=\"article:published_time\" content=\"2026-11-05T00:09:14+00:00\" \/>\n<meta name=\"author\" content=\"admin\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"\u4f5c\u8005\" \/>\n\t<meta name=\"twitter:data1\" content=\"admin\" \/>\n\t<meta name=\"twitter:label2\" content=\"\u9884\u8ba1\u9605\u8bfb\u65f6\u95f4\" \/>\n\t<meta name=\"twitter:data2\" content=\"4 \u5206\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/122586.html\",\"url\":\"https:\/\/www.wsisp.com\/helps\/122586.html\",\"name\":\"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\",\"isPartOf\":{\"@id\":\"https:\/\/www.wsisp.com\/helps\/#website\"},\"datePublished\":\"2026-11-05T00:09:14+00:00\",\"dateModified\":\"2026-11-05T00:09:14+00:00\",\"author\":{\"@id\":\"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41\"},\"breadcrumb\":{\"@id\":\"https:\/\/www.wsisp.com\/helps\/122586.html#breadcrumb\"},\"inLanguage\":\"zh-Hans\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/www.wsisp.com\/helps\/122586.html\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/122586.html#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"\u9996\u9875\",\"item\":\"https:\/\/www.wsisp.com\/helps\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/#website\",\"url\":\"https:\/\/www.wsisp.com\/helps\/\",\"name\":\"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3\",\"description\":\"\u9999\u6e2f\u670d\u52a1\u5668_\u9999\u6e2f\u4e91\u670d\u52a1\u5668\u8d44\u8baf_\u670d\u52a1\u5668\u5e2e\u52a9\u6587\u6863_\u670d\u52a1\u5668\u6559\u7a0b\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/www.wsisp.com\/helps\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"zh-Hans\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41\",\"name\":\"admin\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"zh-Hans\",\"@id\":\"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery\",\"contentUrl\":\"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery\",\"caption\":\"admin\"},\"sameAs\":[\"http:\/\/wp.wsisp.com\"],\"url\":\"https:\/\/www.wsisp.com\/helps\/author\/admin\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/www.wsisp.com\/helps\/122586.html","og_locale":"zh_CN","og_type":"article","og_title":"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","og_description":"\u4ee5\u4e0b\u662f\u9488\u5bf9\u300a\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1：RESTful API JSON\u5951\u7ea6\u300b\u7684\u66f4\u591a\u4ee3\u7801\u793a\u4f8b\u8865\u5145，\u4e3b\u8981\u8986\u76d6 .NET 8\/9 \u65f6\u4ee3\u6700\u5e38\u89c1\u7684\u51e0\u79cd\u5b9e\u73b0\u65b9\u5f0f，\u4ee5\u53ca\u5b9e\u9645\u5de5\u4e1a\u9879\u76ee\u4e2d\u6700\u5e38\u9047\u5230\u7684\u51e0\u79cd\u573a\u666f\u3002 \u6211\u5c06\u6309\u4ee5\u4e0b\u5206\u7c7b\u7ed9\u51fa\u66f4\u8be6\u7ec6\u3001\u53ef\u76f4\u63a5\u590d\u5236\u7c98\u8d34\u7684\u793a\u4f8b\u4ee3\u7801： \u7edf\u4e00\u54cd\u5e94\u6a21\u578b（\u57fa\u7c7b \u6cdb\u578b）\u5168\u5c40\u5f02\u5e38\u5904\u7406\u4e2d\u95f4\u4ef6\u63a7\u5236\u5668\u5e38\u7528\u5199\u6cd5（GET \/ PATCH \/ POST \u5e26\u5e42\u7b49）\u53c2\u6570\u6821\u9a8c \u4e1a\u52a1","og_url":"https:\/\/www.wsisp.com\/helps\/122586.html","og_site_name":"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","article_published_time":"2026-11-05T00:09:14+00:00","author":"admin","twitter_card":"summary_large_image","twitter_misc":{"\u4f5c\u8005":"admin","\u9884\u8ba1\u9605\u8bfb\u65f6\u95f4":"4 \u5206"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/www.wsisp.com\/helps\/122586.html","url":"https:\/\/www.wsisp.com\/helps\/122586.html","name":"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6 - \u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","isPartOf":{"@id":"https:\/\/www.wsisp.com\/helps\/#website"},"datePublished":"2026-11-05T00:09:14+00:00","dateModified":"2026-11-05T00:09:14+00:00","author":{"@id":"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41"},"breadcrumb":{"@id":"https:\/\/www.wsisp.com\/helps\/122586.html#breadcrumb"},"inLanguage":"zh-Hans","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.wsisp.com\/helps\/122586.html"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/www.wsisp.com\/helps\/122586.html#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"\u9996\u9875","item":"https:\/\/www.wsisp.com\/helps"},{"@type":"ListItem","position":2,"name":"\u5de5\u4e1a\u4e0a\u4f4d\u673a\u63a5\u53e3\u89c4\u8303\u8bbe\u8ba1\uff1aRESTful API + JSON\u5951\u7ea6"}]},{"@type":"WebSite","@id":"https:\/\/www.wsisp.com\/helps\/#website","url":"https:\/\/www.wsisp.com\/helps\/","name":"\u7f51\u7855\u4e92\u8054\u5e2e\u52a9\u4e2d\u5fc3","description":"\u9999\u6e2f\u670d\u52a1\u5668_\u9999\u6e2f\u4e91\u670d\u52a1\u5668\u8d44\u8baf_\u670d\u52a1\u5668\u5e2e\u52a9\u6587\u6863_\u670d\u52a1\u5668\u6559\u7a0b","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.wsisp.com\/helps\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"zh-Hans"},{"@type":"Person","@id":"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/358e386c577a3ab51c4493330a20ad41","name":"admin","image":{"@type":"ImageObject","inLanguage":"zh-Hans","@id":"https:\/\/www.wsisp.com\/helps\/#\/schema\/person\/image\/","url":"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery","contentUrl":"https:\/\/gravatar.wp-china-yes.net\/avatar\/?s=96&d=mystery","caption":"admin"},"sameAs":["http:\/\/wp.wsisp.com"],"url":"https:\/\/www.wsisp.com\/helps\/author\/admin"}]}},"_links":{"self":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/posts\/122586","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/comments?post=122586"}],"version-history":[{"count":0,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/posts\/122586\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/media?parent=122586"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/categories?post=122586"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/tags?post=122586"},{"taxonomy":"topic","embeddable":true,"href":"https:\/\/www.wsisp.com\/helps\/wp-json\/wp\/v2\/topic?post=122586"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}