.NET 的 WebApi 项目必要可配置项都有哪些？
目录
在开发一个.NET 的 WebApi 项目时，合理的配置是确保项目高效、稳定运行，并具备良好的可维护性和扩展性的关键。本文将详细探讨.NET WebApi 项目中一些必要的可配置项。
一、数据库配置
（一）选择合适的数据库提供程序
.NET 支持多种数据库，如 SQL Server、MySQL、Oracle 等，每种数据库都有相应的官方或第三方提供程序。以 SQL Server 为例，常用的是Microsoft.EntityFrameworkCore.SqlServer。通过 NuGet 包管理器，在项目中安装此包，即可引入 SQL Server 的相关支持。对于 MySQL，可以安装MySql.Data.EntityFrameworkCore；对于 Oracle，可能需要Oracle.EntityFrameworkCore等，具体取决于所使用的数据库版本和开发需求。
（二）配置数据库连接字符串
- 在配置文件中定义连接字符串：通常在appsettings.json文件中进行配置。例如，对于 SQL Server：
{
"ConnectionStrings": {
"DefaultConnection": "Server=YOUR_SERVER_NAME;Database=YOUR_DATABASE_NAME;User ID=YOUR_USERNAME;Password=YOUR_PASSWORD;Trusted_Connection=False;MultipleActiveResultSets=true"
}
}
其中，YOUR_SERVER_NAME是数据库服务器名称，YOUR_DATABASE_NAME是数据库名称，YOUR_USERNAME和YOUR_PASSWORD是登录数据库的凭证。如果使用 Windows 身份验证，可以将User ID和Password替换为Trusted_Connection=True。
- 在项目中读取连接字符串：在Program.cs文件中，可以通过以下方式读取配置文件中的连接字符串：
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<YourDbContext>(options =>
options.UseSqlServer(connectionString));
这里的YourDbContext是继承自DbContext的自定义数据库上下文类，用于管理与数据库的交互。
（三）数据库迁移（以 EF Core 为例）
- 安装相关工具包：除了数据库提供程序包，还需要安装Microsoft.EntityFrameworkCore.Design包，用于执行数据库迁移命令。
- 创建数据库上下文类：定义一个继承自DbContext的类，例如：
using Microsoft.EntityFrameworkCore;
public class YourDbContext : DbContext
{
public YourDbContext(DbContextOptions<YourDbContext> options) : base(options)
{
}
// 定义DbSet属性来映射数据库表
public DbSet<YourEntity> YourEntities { get; set; }
}
其中，YourEntity是与数据库表对应的实体类。
- 执行迁移命令：在包管理器控制台中，切换到包含YourDbContext类的项目，执行以下命令：
- dotnet ef migrations add InitialCreate：此命令会创建一个新的迁移，InitialCreate是迁移的名称，可以根据实际情况修改。它会根据当前YourDbContext类的定义和已有的数据库结构，生成用于创建或更新数据库的迁移脚本。
- dotnet ef database update：该命令会将数据库更新到最新的迁移状态，即执行上一步生成的迁移脚本，创建或更新数据库架构。
二、依赖注入配置
（一）理解依赖注入
依赖注入（Dependency Injection，简称 DI）是一种设计模式，它通过将对象的创建和依赖关系的管理从对象本身转移到外部容器中，从而实现松耦合的设计。在.NET WebApi 项目中，依赖注入由框架内置的服务容器来管理。
（二）注册服务
- 内置服务注册：在Program.cs文件中，builder.Services用于注册各种服务。例如，注册一个用于日志记录的服务：
builder.Services.AddLogging();
这将启用框架内置的日志记录功能。
- 自定义服务注册：假设有一个业务逻辑服务YourService，它实现了IYourService接口：
public interface IYourService
{
void DoSomething();
}
public class YourService : IYourService
{
public void DoSomething()
{
// 业务逻辑代码
}
}
在Program.cs中注册该服务：
builder.Services.AddScoped<IYourService, YourService>();
这里使用AddScoped方法，表示该服务在每个请求范围内是单例的，即每次请求都会创建一个新的YourService实例，但在同一个请求中，多次获取IYourService都会返回同一个实例。其他常见的生命周期方法还有AddSingleton（整个应用程序生命周期内单例）和AddTransient（每次请求都会创建一个新实例）。
（三）使用依赖注入
在控制器或其他需要使用服务的地方，通过构造函数注入依赖。例如，在一个控制器中使用IYourService：
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("[controller]")]
public class YourController : ControllerBase
{
private readonly IYourService _yourService;
public YourController(IYourService yourService)
{
_yourService = yourService;
}
[HttpGet]
public IActionResult Get()
{
_yourService.DoSomething();
return Ok("Service executed successfully");
}
}
这样，当控制器实例化时，服务容器会自动将IYourService的实例注入到控制器的构造函数中。
三、Swagger 配置
（一）安装 Swagger 相关包
通过 NuGet 包管理器安装Swashbuckle.AspNetCore包，它提供了在.NET 项目中集成 Swagger 的功能。Swagger 是一个用于生成、描述、调用和可视化 RESTful Web 服务的工具，能极大地简化接口文档的生成和测试工作。
（二）配置 Swagger 服务
在Program.cs文件中，添加 Swagger 服务配置：
using Swashbuckle.AspNetCore.SwaggerGen;
using Microsoft.OpenApi.Models;
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "Your WebApi Title",
Version = "v1",
Description = "A detailed description of your WebApi",
Contact = new OpenApiContact
{
Name = "Your Name",
Email = "[email protected]",
Url = new Uri("https://example.com")
}
});
// 配置XML注释文件路径，用于生成详细的接口文档
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
这里，SwaggerDoc方法定义了 API 的版本（v1）、标题、描述和联系人等信息。IncludeXmlComments方法用于指定包含 XML 注释的文件路径，以便 Swagger 能生成更详细的接口文档，包括参数说明、返回值说明等。要生成 XML 注释文件，需要在项目属性的 “生成” 选项卡中，勾选 “XML 文档文件”。
（三）启用 Swagger 中间件
在Program.cs的Configure方法中，启用 Swagger 中间件：
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your WebApi V1");
c.RoutePrefix = "swagger";// 设置Swagger UI的访问路径
});
UseSwagger方法用于生成 Swagger JSON 文档，UseSwaggerUI方法用于启用 Swagger UI 界面，通过该界面可以方便地查看和测试 API 接口。SwaggerEndpoint方法指定了 Swagger JSON 文档的路径和版本描述，RoutePrefix设置了 Swagger UI 的访问路径，例如，访问http://localhost:YOUR_PORT/swagger即可打开 Swagger UI 界面。
四、接口接收和输出大小写配置
（一）接口接收大小写配置
默认情况下，.NET WebApi 在接收 JSON 数据时，会尝试匹配属性名，不区分大小写。但在某些场景下，可能需要严格区分大小写。要实现严格区分大小写，可以在Program.cs中进行如下配置：
builder.Services.AddControllers()
.AddJsonOptions(options =>
{
options.JsonSerializerOptions.PropertyNameCaseInsensitive = false;
});
这将使 WebApi 在反序列化 JSON 数据时，严格按照属性名的大小写进行匹配。如果客户端发送的 JSON 数据中的属性名大小写与模型类中的属性名不完全一致，将导致属性值无法正确绑定。
（二）接口输出大小写配置
- 使用 Newtonsoft.Json：在一些旧版本的.NET 项目中，可能还在使用 Newtonsoft.Json 库进行 JSON 序列化和反序列化。要配置输出的 JSON 数据的大小写，可以安装Microsoft.AspNetCore.Mvc.NewtonsoftJson包，并在Program.cs中进行如下配置：
builder.Services.AddControllers()
.AddNewtonsoftJson(options =>
{
options.SerializerSettings.ContractResolver = new DefaultContractResolver();
});
DefaultContractResolver默认会将属性名以驼峰命名法输出。如果希望以原属性名输出（即不进行命名转换），可以使用CamelCasePropertyNamesContractResolver来实现驼峰命名法输出，或者自定义ContractResolver来满足特定的命名规则。
- 使用 System.Text.Json：在较新的.NET 版本中，默认使用System.Text.Json库。要配置输出的 JSON 数据的大小写，可以在Program.cs中进行如下配置：
builder.Services.AddControllers()
.AddJsonOptions(options =>
{
options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
});
这里使用JsonNamingPolicy.CamelCase将属性名转换为驼峰命名法输出。如果希望以原属性名输出，可以设置PropertyNamingPolicy为null。
五、跨域配置
（一）什么是跨域
当一个前端应用程序运行在一个域名下，而它试图访问另一个域名下的 API 时，就会出现跨域问题。这是因为浏览器的同源策略限制了不同源（协议、域名、端口中有一个不同即为不同源）之间的资源访问。在开发 WebApi 项目时，尤其是与前端分离开发时，经常需要处理跨域问题。
（二）配置跨域
- 在配置文件中定义跨域规则：在appsettings.json文件中，可以定义允许跨域的源。例如：
{
"AllowedOrigins": [
"http://localhost:3000",
"https://example.com"
]
}
这里列出了允许跨域访问的前端应用的 URL。
- 在项目中启用跨域中间件：在Program.cs文件中，添加跨域中间件配置：
using Microsoft.AspNetCore.Cors.Infrastructure;
var allowedOrigins = builder.Configuration.GetSection("AllowedOrigins").Get<string[]>();
var corsBuilder = new CorsPolicyBuilder();
corsBuilder.AllowAnyHeader();
corsBuilder.AllowAnyMethod();
corsBuilder.WithOrigins(allowedOrigins);
builder.Services.AddCors(options =>
{
options.AddPolicy("AllowSpecificOrigins", corsBuilder.Build());
});
这里创建了一个名为AllowSpecificOrigins的 CORS 策略，允许指定源（从配置文件中读取）、任何 HTTP 方法和任何请求头。然后在Configure方法中启用该策略：
app.UseCors("AllowSpecificOrigins");
如果希望允许所有源跨域访问（不推荐在生产环境中使用，因为存在安全风险），可以简化配置为：
builder.Services.AddCors(options =>
{
options.AddPolicy("AllowAll", builder =>
{
builder.AllowAnyOrigin()
.AllowAnyMethod()
.AllowAnyHeader();
});
});
并在Configure方法中使用app.UseCors("AllowAll");
六、身份验证与授权配置
（一）身份验证
- 选择身份验证方案：.NET WebApi 支持多种身份验证方案，如 JWT（JSON Web Token）、OAuth 2.0、Windows 身份验证等。以 JWT 为例，首先需要安装Microsoft.AspNetCore.Authentication.JwtBearer包。
- 配置 JWT 身份验证：在Program.cs中进行如下配置：
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;
var jwtSettings = builder.Configuration.GetSection("JwtSettings");
var key = Encoding.ASCII.GetBytes(jwtSettings["SecretKey"]);
builder.Services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.RequireHttpsMetadata = false;
options.SaveToken = true;
options.TokenValidationParameters = new TokenValidationParameters
{
ValidateIssuer = true,
ValidateAudience = true,
ValidateLifetime = true,
ValidateIssuerSigningKey = true,
ValidIssuer = jwtSettings["Issuer"],
ValidAudience = jwtSettings["Audience"],
IssuerSigningKey = new SymmetricSecurityKey(key)
};
});
这里从配置文件appsettings.json中的JwtSettings节点读取 JWT 的相关配置，如密钥（SecretKey）、颁发者（Issuer）和受众（Audience）。配置TokenValidationParameters用于验证 JWT 的有效性。
（二）授权
- 基于角色的授权：在控制器或控制器方法上应用Authorize特性，结合角色信息进行授权。首先，在Program.cs中添加授权服务：
builder.Services.AddAuthorization();
然后，在控制器中使用Authorize特性。例如：
[ApiController]
[Route("[controller]")]
[Authorize(Roles = "Admin")]
public class AdminController : ControllerBase
{
// 只有具有Admin角色的用户才能访问此控制器的方法
}
这里表示只有具有Admin角色的用户才能访问AdminController中的方法。
- 基于策略的授权：可以定义更复杂的授权策略。在Program.cs中定义策略：
builder.Services.AddAuthorization(options =>
{
options.AddPolicy("MustBeOver21", policy =>
policy.RequireAssertion(context =>
{
// 这里可以编写自定义的授权逻辑，例如检查用户年龄
var user = context.User;
// 假设用户声明中包含年龄信息
var ageClaim = user.FindFirst("Age");
if (ageClaim != null)
{
int age = int.Parse(ageClaim.Value);
return age >= 21;
}
return false;
}));
});
然后在控制器中使用该策略：
[ApiController]
[Route("[controller]")]
[Authorize(Policy = "MustBeOver21")]
public class AgeRestrictedController : ControllerBase
{
// 只有满足MustBeOver21策略的用户才能访问此控制器的方法
}
这样可以根据具体的业务需求，灵活地定义和应用授权策略。
七、日志配置
（一）选择日志框架
.NET 提供了多种日志框架，如内置的ILogger接口及相关实现，还有第三方的Serilog、NLog等。以Serilog为例，首先通过 NuGet 包管理器安装Serilog.AspNetCore、Serilog.Sinks.Console等相关包。Serilog.AspNetCore用于将 Serilog 集成到ASP.NET Core 应用中，Serilog.Sinks.Console用于将日志输出到控制台。
（二）配置 Serilog
在Program.cs中进行如下配置：
using Serilog;
using Serilog.Events;
var logger = new LoggerConfiguration()
.MinimumLevel.Override("Microsoft", LogEventLevel.Information)
.Enrich.FromLogContext()
.WriteTo.Console()
.CreateLogger();
builder.Logging.ClearProviders();
builder.Logging.AddSerilog(logger);
这里创建了一个LoggerConfiguration实例，配置了日志的最低级别（将Microsoft命名空间下的日志级别覆盖为Information，即只记录Information级别及以上的日志），启用了从日志上下文获取信息的功能，并将日志输出到控制台。然后通过builder.Logging.ClearProviders()清除默认的日志提供程序，再添加 Serilog 作为日志记录工具。
