当前位置：首页 > 行业动态 > 正文

c#做api

admin
行业动态
2025-02-26
5

用C#做API通常使用ASP.NET Core框架，通过创建控制器和定义路由来处理HTTP请求并返回响应。

C# 做 API 的详细步骤与要点

在当今数字化时代，API（应用程序编程接口）已成为不同软件系统之间交互和通信的关键桥梁，C#作为一种功能强大且广泛应用的编程语言，为开发高效、稳定的API提供了坚实的基础，下面将详细介绍使用C#做API的相关步骤、技术和最佳实践。

一、环境搭建

1、安装开发工具

Visual Studio：这是一款功能强大的集成开发环境（IDE），支持C#开发，从官方网站下载并安装适合自己操作系统的版本，安装过程中可选择.NET桌面开发工作负载等相关组件，以确保对C#项目开发的全面支持。

.NET SDK：.NET SDK是开发.NET应用程序所需的软件开发工具包，包含了编译器、运行时等必要组件，可以从.NET官方网站下载安装最新版本的SDK，它允许开发者使用命令行工具创建和管理C#项目。

2、配置开发环境

安装完成后，打开Visual Studio，通过“文件”->“新建”->“项目”创建一个新的C#项目，在项目模板中选择“ASP.NET Core Web API”项目模板，这是专门用于创建Web API项目的模板，它会生成基本的API项目结构，包括控制器、模型等文件夹。

二、设计API架构

1、确定API的功能和端点

根据业务需求，明确API需要提供哪些功能，例如用户注册、登录、获取商品信息、提交订单等，每个功能对应一个或多个API端点，端点的命名应遵循一定的规范，通常采用RESTful风格的命名方式，如“/api/users/register”表示用户注册端点，“/api/products/{id}”表示获取指定ID的商品信息端点，{id}”为路径参数。

2、设计请求和响应格式

请求格式：常见的请求格式有GET、POST、PUT、DELETE等，GET请求用于获取资源，不应改变服务器状态；POST请求用于创建新资源；PUT请求用于更新现有资源；DELETE请求用于删除资源，要确定请求中是否需要携带参数，如查询参数、请求体参数等，对于请求体参数，通常使用JSON格式进行数据传输，因为它具有良好的可读性和扩展性。

响应格式：API的响应应包含状态码、消息和数据等信息，状态码遵循HTTP协议标准，如200表示成功，400表示客户端错误，500表示服务器错误等，消息用于向客户端说明操作结果，数据则是返回给客户端的具体信息，通常也采用JSON格式，成功的响应可能如下：

{
  "statusCode": 200,
  "message": "操作成功",
  "data": {
    "userId": "12345",
    "username": "JohnDoe"
  }
}

三、创建模型类

1、定义数据结构

根据API需要处理的数据，创建相应的模型类，模型类的属性应与数据库表的字段相对应，或者与接收和返回的数据结构相匹配，对于一个用户注册功能，可能需要创建一个User模型类：

public class User
{
  public int Id { get; set; }
  public string Username { get; set; }
  public string Password { get; set; }
  public string Email { get; set; }
}

2、数据验证

为了确保数据的合法性和准确性，在模型类中使用数据注解进行验证，可以使用[Required]注解来标记必填字段，使用[StringLength]注解来限制字符串长度，使用[EmailAddress]注解来验证邮箱格式等：

public class User
{
  [Key]
  public int Id { get; set; }
  
  [Required]
  [StringLength(maximumLength: 50)]
  public string Username { get; set; }
  
  [Required]
  [StringLength(maximumLength: 100)]
  public string Password { get; set; }
  
  [Required]
  [EmailAddress]
  public string Email { get; set; }
}

这样，当接收到客户端发送的数据时，框架会自动进行验证，如果验证不通过，会返回相应的错误信息给客户端。

四、编写控制器

1、创建控制器类

在项目中创建控制器类，通常继承自ControllerBase类，控制器类负责处理客户端的请求，并根据请求调用相应的业务逻辑方法，创建一个UsersController类来处理与用户相关的请求：

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
  // 在这里添加处理请求的方法
}

2、实现动作方法

c#做api 第1张

在控制器类中，根据设计的API端点和方法，实现相应的动作方法，实现用户注册的动作方法：

[HttpPost("register")]
public async Task<ActionResult<User>> Register([FromBody] User user)
{
  if (!ModelState.IsValid)
  {
    return BadRequest(ModelState);
  }
  // 在这里添加保存用户信息到数据库的逻辑
  return Ok(user);
}

上述代码中，[HttpPost("register")]注解表示该方法处理POST请求，并将请求路径映射到“/api/users/register”。[FromBody]注解表示从请求体中获取参数，并将其绑定到User模型类的实例上，在方法内部，首先检查模型验证是否通过，如果不通过则返回BadRequest响应；如果通过，则执行保存用户信息到数据库的操作，并返回Ok响应，同时将用户信息作为响应数据返回给客户端。

五、集成数据库

1、选择数据库

C#做API可以集成多种数据库，如SQL Server、MySQL、SQLite等，根据项目的需求和规模选择合适的数据库，对于小型项目或本地开发，可以选择SQLite；对于大型项目或生产环境，可以选择SQL Server或MySQL等关系型数据库。

2、配置数据库连接

在项目的配置文件（如appsettings.json）中配置数据库连接字符串：

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\mssqllocaldb;Database=MyDatabase;Trusted_Connection=True;MultipleActiveResultSets=true"
  }
}

在项目中使用依赖注入的方式引入DbContext类，并在DbContext类中配置数据库连接和模型映射：

public class ApplicationDbContext : DbContext
{
  public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options)
  {
  }
  
  public DbSet<User> Users { get; set; }
  // 在这里添加其他模型的DbSet属性
}

3、执行数据库操作

在控制器的动作方法中，通过依赖注入获取DbContext实例，并使用它来执行数据库操作，如插入、查询、更新和删除数据，在用户注册的动作方法中保存用户信息到数据库：

[HttpPost("register")]
public async Task<ActionResult<User>> Register([FromBody] User user)
{
  if (!ModelState.IsValid)
  {
    return BadRequest(ModelState);
  }
  using (var context = new ApplicationDbContext())
  {
    context.Users.Add(user);
    await context.SaveChangesAsync();
  }
  return Ok(user);
}

上述代码中，通过using语句创建ApplicationDbContext的实例，并使用其Users属性来访问用户表，将新的用户信息添加到Users集合中，并调用SaveChangesAsync方法将更改保存到数据库中。

六、异常处理和日志记录

1、异常处理

在API开发过程中，难免会遇到各种异常情况，如数据库连接失败、数据验证失败、业务逻辑错误等，为了提高API的稳定性和用户体验，需要进行全局异常处理，可以通过创建自定义的异常处理中间件来实现：

public class ExceptionHandlingMiddleware
{
  private readonly RequestDelegate next;
  private readonly ILogger logger;
  public ExceptionHandlingMiddleware(RequestDelegate next, ILoggerFactory loggerFactory)
    {
      this.next = next;
      this.logger = loggerFactory.CreateLogger<ExceptionHandlingMiddleware>();
    }
  
  public async Task InvokeAsync(HttpContext context)
    {
      try
      {
        await next(context);
      }
      catch (Exception ex)
      {
        logger.LogError($"Unhandled exception: {ex.Message}");
        context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;
        await context.Response.WriteAsJsonAsync(new { statusCode = 500, message = "服务器内部错误" });
      }
    }
}

在Startup.cs文件中配置该中间件：

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
  app.UseMiddleware<ExceptionHandlingMiddleware>();
  // 其他中间件配置
}

2、日志记录

日志记录对于排查问题和监控系统运行状态非常重要，除了在异常处理中间件中记录日志外，还可以在关键业务逻辑处添加日志记录，在用户注册成功后记录日志：

[HttpPost("register")]
public async Task<ActionResult<User>> Register([FromBody] User user)
{
  if (!ModelState.IsValid)
  {
    return BadRequest(ModelState);
  }
  using (var context = new ApplicationDbContext())
  {
    context.Users.Add(user);
    await context.SaveChangesAsync();
    logger.LogInformation($"User registered: {user.Username}");
  }
  return Ok(user);
}

上述代码中，使用logger.LogInformation方法记录用户注册成功的信息，包括用户名等关键信息，这样，在查看日志时可以清楚地了解系统的运行情况。

七、测试和部署

1、单元测试

编写单元测试用例来测试各个模块的功能是否正确，可以使用xUnit、NUnit等测试框架来进行单元测试，测试用户注册功能：

public class UsersControllerTests
{
  private readonly UsersController controller;
  private readonly ApplicationDbContext context;
  public UsersControllerTests()
    {
      context = new ApplicationDbContext(new DbContextOptionsBuilder<ApplicationDbContext>().UseInMemoryDatabase(new InMemoryDatabase()).Options);
      controller = new UsersController(context);
    }
  
  [Fact]
  public async Task Register_ShouldReturnSuccess_WhenGivenValidUser()
    {
      // Arrange
      var user = new User { Username = "TestUser", Password = "TestPassword", Email = "test@example.com" };
      // Act
      var result = await controller.Register(user);
      // Assert
      Assert.IsType<OkObjectResult>(result);
      Assert.Equal(200, result.Value.StatusCode);
    }
}

上述代码中，使用InMemoryDatabase作为测试数据库，创建了一个UsersController的实例，并向其Register方法传递一个有效的用户对象，然后断言返回的结果是一个OkObjectResult类型，且状态码为200，通过编写更多的单元测试用例，可以覆盖各种场景和边界条件，确保代码的正确性。

2、集成测试

除了单元测试外，还需要进行集成测试，以测试整个API在不同环境下的运行情况，可以使用Postman、Swagger等工具来进行集成测试，通过向API发送各种请求，并检查返回的结果是否符合预期，来验证API的功能是否正常，使用Postman测试用户注册接口：

打开Postman软件。

选择POST请求方法。

在URL栏中输入“http://localhost:5000/api/users/register”。

在Body栏中选择raw格式，并输入JSON格式的用户数据，如：{"username":"TestUser","password":"TestPassword","email":"test@example.com"}。

点击Send按钮发送请求。

查看返回的结果，应该得到一个状态码为200的响应，且响应数据中包含用户的信息。

3、部署

当API开发完成并通过测试后，就可以将其部署到生产环境中，可以选择将API部署到云平台上，如Azure App Service、AWS Elastic Beanstalk等；也可以部署到自己的服务器上，在部署过程中，需要注意配置服务器的环境变量、数据库连接等信息，并确保服务器的安全性和稳定性。

八、安全考虑

1、身份认证和授权

根据API的安全需求，选择合适的身份认证和授权方式，常见的身份认证方式有基本认证、Bearer令牌认证、OAuth认证等，使用JWT（JSON Web Token）进行身份认证和授权：

在用户注册或登录成功后，生成一个JWT令牌，并将其返回给客户端，客户端在后续的请求中需要在请求头中携带该令牌。Authorization: Bearer <token>。

在API端，通过中间件来验证JWT令牌的有效性，如果令牌有效，则允许访问受保护的资源；如果令牌无效或已过期，则返回未授权的响应，可以使用一些现成的JWT库来实现这一功能，如Microsoft.IdentityModel.Tokens等。

2、数据加密

对于敏感数据，如用户的密码、信用卡信息等，需要进行加密存储和传输，可以使用哈希算法对密码进行加密存储，如SHA-256；在数据传输过程中，可以使用HTTPS协议来确保数据的安全性，HTTPS是一种安全的HTTP协议，它在HTTP的基础上添加了SSL/TLS加密层，可以防止数据被窃取和改动，在配置HTTPS时，需要购买SSL证书，并将其配置到服务器上。

3、防止常见的安全破绽

API开发过程中需要注意防止一些常见的安全破绽，如SQL注入、XSS攻击、CSRF攻击等，可以通过以下措施来预防这些破绽：

SQL注入：使用参数化查询或ORM框架来执行数据库操作，避免直接拼接SQL语句，在使用Entity Framework时，通过DbContext的LINQ查询或Find方法来执行数据库操作，而不是使用SqlQuery方法拼接SQL语句。

XSS攻击：对用户输入的数据进行HTML编码或过滤，防止反面脚本的注入，可以使用一些库或框架来帮助实现这一功能，如AntiXSS库等。

CSRF攻击：在表单提交或敏感操作中添加CSRF令牌，并在服务器端验证令牌的有效性，可以使用一些中间件或库来实现CSRF防护，如Microsoft.AspNetCore.Antiforgery等。