.NET Core 构建Rest服务实验手册(二)

在本系列的上一篇文章中，演示了如何安装.NET Core开发环境，并构建了一个项目雏形。在本文中，将演示如何构建自己的API。

项目结构

通过 VS Code 右边的 Explorer 可以看到，项目的目录结构如下:

TODOAPI
   + .vscode
   + bin
   + Controllers
   + obj
   + Properties
    appsettings.Development.json
    appsettings.json
    Program.cs
    Startup.cs
    TodoApi.csproj

其中:
.vscode - 是 VS Code 使用的目录，可以不必理会
bin - 项目编译，打包所使用的目录，现在可以不必理会
Controllers - 用于组织 WebApi 的 Controller 的源代码
obj - 项目编译的中间码
Properties - 用于存放项目相关的一些配置信息
Programs.cs - 程序入口
Startup.cs - 通常用于启动时进行初始化

ValuesController 解析

接下来，我们来研究项目自动生成的 VaulesController 类，打开 ValuesController.cs 文件，

先看类的定义，

1
2
3

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase

该类的是继承于 ControllerBase, 这是 .NET Core MVC 中处理 WEB 请求的基类。不要通过从 Controller 类派生来创建 Web API 控制器。 Controller 派生自 ControllerBase，并添加对视图的支持，因此它用于处理 Web 页面，而不是 Web API 请求

Route 注解为该类提供了类（资源）级别的路由，”api/[controller]” 的意思是指定该资源的路径为 http(s)://host:port/api/[controller] - 其中 controller 是去掉 “Controller” 后缀之后的名字，如 ValuesController 的名字为 Values。

其次来看方法的定义，如：

[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
    return new string[] { "value1", "value2" };
}

方法使用了 HttpGet 来修饰，将映射为使用 GET 方法访问 api/values。

方法返回 ActionResult 类型，该类型封装了 HTTP 相关的细节，包括 HTTP 返回码等。

构建一个新的 Controller

仿造 ValuesController, 让我们来构建一个最简单的 WebApi。

在后台 WebApi 系统开发中，通常我习惯提供一个最简单的 ok api 给负载均衡用，负载均衡器用这个 api 检查后端服务的健康状况。

在 Controllers 目录中新建一个C#程序文件: OkController.cs, 定义 OkController 类并定义一个 Get 方法:

using Microsoft.AspNetCore.Mvc;

namespace TodoApi.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class OkController : ControllerBase
    {
        
        public ActionResult<string> Get()
        {
            return "ok";
        }

    }
}

在 Terminal 中执行:

1	dotnet run

然后在浏览器中访问 https://localhost:5001/api/ok ，可以看到浏览器简单显示 “ok”。

定义 Todo 实例类

因为在示例中需要管理待办事项（Todo),所以我们定义一个 Todo 的类来表示待办事项的相关信息。在项目根目录中新建一个 Model 目录，再在里面建一个新的C#文件: Todo.cs。内容如下:

namespace TodoApi.Model
{
    public class Todo
    {
        public long Id { get; set; }
        public string Title { get; set; }

        public string Desc { get; set;}
        
        public bool IsComplete { get; set; }
    }
}

定义 TodoController 类

在 Controllers 目录中新建C#程序文件: TodoController.cs, 再在类中增加一个api，返回Todo的列表。程序如下:

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using TodoApi.Model;

namespace TodoApi.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TodoController : ControllerBase
    {

       [HttpGet]
        public ActionResult<IEnumerable<Todo>> Get()
        {
            List<Todo> todos = new List<Todo>();
            todos.Add(new Todo() {Id = 1, Title = "task1", Desc = "description for task1", IsComplete = false});
            todos.Add(new Todo() {Id = 2, Title = "task2", Desc = "description for task2", IsComplete = false});

            return todos;
        }

    }
}

在 Terminal 中执行:

1	dotnet run

然后在浏览器中访问 https://localhost:5001/api/todo ，可以看到浏览器简单显示:

1	[{"id":1,"title":"task1","desc":"description for task1","isComplete":false},{"id":2,"title":"task2","desc":"description for task2","isComplete":false}]

下一步

在下一篇文章中，我们将在项目中引入数据库，并处理用户输入的数据。