C#中创建统一API接口的实现方案_Asp.net

一、技术选型与架构设计

框架选择
- asp.net core (6.0+)
- restful api 规范
核心组件
- 统一响应格式：标准化 json 响应结构
- 全局异常处理：统一错误返回
- 版本控制：api 版本管理
- 认证授权：jwt bearer 认证
- 数据验证：model validation
- 日志记录：serilog 或内置 ilogger
- swagger 文档：openapi 规范支持
架构分层

api layer (controllers)
↓
application layer (services)
↓
domain layer (models, interfaces)
↓
infrastructure layer (repositories)

二、完整实现步骤

1. 创建项目

dotnet new webapi -n unifiedapidemo

2. 添加 nuget 包

dotnet add package microsoft.aspnetcore.mvc.versioning
dotnet add package swashbuckle.aspnetcore
dotnet add package microsoft.aspnetcore.authentication.jwtbearer

三、核心代码实现

1. 统一响应模型

public class apiresponse<t>
{
    public int code { get; set; }
    public string message { get; set; }
    public t data { get; set; }
    public datetime timestamp { get; } = datetime.utcnow;

    public static apiresponse<t> success(t data) => new() 
    { 
        code = 200, 
        message = "success", 
        data = data 
    };
    
    public static apiresponse<object> error(int code, string message) => new() 
    { 
        code = code, 
        message = message 
    };
}

2. 全局异常处理中间件

public class exceptionmiddleware
{
    private readonly requestdelegate _next;
    private readonly ilogger<exceptionmiddleware> _logger;

    public exceptionmiddleware(requestdelegate next, ilogger<exceptionmiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async task invokeasync(httpcontext context)
    {
        try
        {
            await _next(context);
        }
        catch (exception ex)
        {
            _logger.logerror(ex, "global exception occurred");
            await handleexceptionasync(context, ex);
        }
    }

    private static task handleexceptionasync(httpcontext context, exception exception)
    {
        context.response.contenttype = "application/json";
        context.response.statuscode = exception switch
        {
            validationexception => statuscodes.status400badrequest,
            unauthorizedaccessexception => statuscodes.status401unauthorized,
            _ => statuscodes.status500internalservererror
        };

        return context.response.writeasjsonasync(apiresponse<object>.error(
            context.response.statuscode,
            exception.message
        ));
    }
}

3. 统一响应包装过滤器

public class apiresponsefilter : iasyncresultfilter
{
    public async task onresultexecutionasync(
        resultexecutingcontext context, 
        resultexecutiondelegate next)
    {
        if (context.result is objectresult objresult)
        {
            var apiresponse = apiresponse<object>.success(objresult.value);
            context.result = new objectresult(apiresponse)
            {
                statuscode = objresult.statuscode
            };
        }
        await next();
    }
}

4. 配置服务（program.cs）

var builder = webapplication.createbuilder(args);

// 添加版本控制
builder.services.addapiversioning(options =>
{
    options.defaultapiversion = new apiversion(1, 0);
    options.assumedefaultversionwhenunspecified = true;
    options.reportapiversions = true;
});

// 配置 swagger
builder.services.addswaggergen(c =>
{
    c.swaggerdoc("v1", new openapiinfo { title = "unified api", version = "v1" });
});

// 添加统一响应过滤器
builder.services.addcontrollers(options =>
{
    options.filters.add<apiresponsefilter>();
});

// 配置 jwt 认证
builder.services.addauthentication(jwtbearerdefaults.authenticationscheme)
    .addjwtbearer(options => 
    {
        options.tokenvalidationparameters = new tokenvalidationparameters
        {
            validateissuer = true,
            validissuer = "your_issuer",
            validateaudience = true,
            validaudience = "your_audience",
            validatelifetime = true,
            issuersigningkey = new symmetricsecuritykey(encoding.utf8.getbytes("your_secret_key"))
        };
    });

var app = builder.build();

// 中间件管道
app.useswagger();
app.useswaggerui();
app.usemiddleware<exceptionmiddleware>();
app.useauthentication();
app.useauthorization();
app.mapcontrollers();
app.run();

5. 控制器示例（带版本控制）

[apicontroller]
[route("api/v{version:apiversion}/[controller]")]
[apiversion("1.0")]
[authorize]
public class productscontroller : controllerbase
{
    [httpget("{id}")]
    [producesresponsetype(typeof(productdto), 200)]
    public iactionresult getproduct(int id)
    {
        var product = new productdto { id = id, name = "sample product" };
        return ok(product);
    }

    [httppost]
    [validatemodel]
    public iactionresult createproduct([frombody] productcreatedto dto)
    {
        // 业务逻辑
        return createdataction(nameof(getproduct), new { id = 1 }, null);
    }
}

6. 模型验证示例

public class productcreatedto
{
    [required]
    [stringlength(100)]
    public string name { get; set; }

    [range(0, 10000)]
    public decimal price { get; set; }
}

public class validatemodelattribute : actionfilterattribute
{
    public override void onactionexecuting(actionexecutingcontext context)
    {
        if (!context.modelstate.isvalid)
        {
            var errors = context.modelstate
                .where(e => e.value.errors.count > 0)
                .todictionary(
                    kvp => kvp.key,
                    kvp => kvp.value.errors.select(e => e.errormessage).toarray()
                );
            
            context.result = new badrequestobjectresult(
                apiresponse<object>.error(400, "validation error", errors)
            );
        }
    }
}

四、运行效果示例

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "sample product"
  },
  "timestamp": "2024-02-20t12:34:56z"
}

错误响应

{
  "code": 400,
  "message": "validation error",
  "data": {
    "price": ["the field price must be between 0 and 10000."]
  },
  "timestamp": "2024-02-20t12:35:10z"
}