从0到1创建.Net8 WebAPI：我踩过的坑和最顺手的步骤

很多人觉得“创建项目”是最简单的一步，但其实里面藏着不少影响后续开发的细节。比如去年我帮朋友做餐饮管理系统的后端时，他一开始用CLI命令dotnet new webapi创建项目，结果忘了加-f net8.0参数，默认用了.Net7框架，后来要兼容新功能不得不重构，白搭了2天时间。所以我现在不管用VS还是CLI，第一步必确认框架版本——这是最基础也最容易忘的点。

如果你像我一样喜欢可视化操作，直接用Visual Studio最顺手：打开VS→点击“创建新项目”→搜索“ASP.NET Core Web API”→选择框架为“.NET 8.0”→一定要勾上“启用OpenAPI支持”（这步能省掉后面配置Swagger的麻烦）→命名项目（比如“RestaurantApi”）→选保存路径→点击“创建”。不到1分钟，项目就初始化好了，自动生成Program.cs、WeatherForecastController这些基础文件。

要是你习惯用命令行，CLI也不差：打开终端→输入dotnet new webapi -n RestaurantApi -f net8.0→回车，等待项目创建完成。这种方式适合快速搭建，比如我在给客户做紧急需求时，用CLI能比VS快10秒——但新手 先从VS开始，因为能直观看到项目结构。

不管用哪种方式，初始化完成后一定要检查csproj文件里的TargetFramework是不是net8.0——这是我去年踩过的第一个坑，当时没检查，写了半天接口才发现框架不对，只能重新来。

创建好项目后，接下来要配置三个“必须用对”的功能：跨域、Swagger、数据库——这三个也是开发者最容易翻车的点。

跨域配置：为什么要配跨域？因为浏览器有个“同源策略”，如果你的前端项目和API不在同一个域名或端口，浏览器会拦截请求。去年我帮另一个客户做项目时，把跨域代码写对了，但放错了位置——我把app.UseCors("AllowAll")放在了app.UseAuthorization()后面，结果前端还是报“跨域错误”。后来查微软文档才知道，UseCors必须放在UseRouting和UseAuthorization之间，正确的顺序是：

var builder = WebApplication.CreateBuilder(args);
// 添加Cors服务
builder.Services.AddCors(options =>
{
 options.AddPolicy("AllowAll", policy =>
 {
 policy.AllowAnyOrigin() // 允许所有来源（生产环境 限制具体域名）
 .AllowAnyMethod() // 允许所有HTTP方法
 .AllowAnyHeader(); // 允许所有请求头
 });
});
var app = builder.Build();
app.UseRouting(); // 先启用路由
app.UseCors("AllowAll"); // 再启用跨域
app.UseAuthorization(); // 最后启用授权
app.MapControllers();
app.Run();

Swagger配置：.Net8默认已经集成了Swagger，但我 再优化一下——加个文档描述和版本，不然前端问“这个接口是做什么的”，你还得一个个解释。比如在Program.cs里加这段代码：

builder.Services.AddSwaggerGen(c =>
{
 c.SwaggerDoc("v1", new OpenApiInfo
 {
 Title = "餐饮管理系统API",
 Version = "v1",
 Description = "包含用户管理、订单管理、菜品管理等接口，支持CRUD操作"
 });
});

然后启动项目，访问http://localhost:5000/swagger，就能看到带描述的Swagger页面——去年我给朋友加了这段后，他的前端同事说“终于不用猜接口用途了”。

数据库配置：大部分项目都要连数据库，我常用EF Core连接SQL Server，步骤很固定：

① 安装NuGet包：右键项目→“管理NuGet程序包”→搜索并安装Microsoft.EntityFrameworkCore.SqlServer（SQL Server驱动）、Microsoft.EntityFrameworkCore.Design（迁移工具）。

② 写DbContext：新建Data文件夹→创建RestaurantDbContext.cs：

using Microsoft.EntityFrameworkCore;
using RestaurantApi.Models; // 假设你有User、Order这些模型
public class RestaurantDbContext DbContext
{
 public RestaurantDbContext(DbContextOptions options) base(options) { }
 // 映射数据库表
 public DbSet Users { get; set; }
 public DbSet Orders { get; set; }
 public DbSet Dishes { get; set; }
}

③ 配置连接字符串：打开appsettings.json→在ConnectionStrings里加：

"ConnectionStrings": {
 "DefaultConnection": "Server=(localdb)mssqllocaldb;Database=RestaurantDb;Trusted_Connection=True;"
}

④ 注册DbContext：在Program.cs里加builder.Services.AddDbContext(options => options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));。

这里要注意：(localdb)mssqllocaldb是SQL Server LocalDB的默认实例名，如果你用的是远程数据库，要把Server改成数据库地址，比如Server=192.168.1.100;Database=RestaurantDb;User Id=sa;Password=123456;——去年我帮朋友连远程数据库时，把Server写成了localhost，结果连不上，后来改成服务器IP才解决。

配置好核心功能后，就能写接口了。我 了一个“万能CRUD模板”，不管是用户管理还是订单管理，都能套着用——去年我用这个模板写了10几个接口，没出过错。

比如写用户接口：新建Controllers文件夹→创建UserController.cs→继承ControllerBase→注入RestaurantDbContext：

[ApiController]
[Route("api/[controller]")]
public class UserController ControllerBase
{
 private readonly RestaurantDbContext _context;
 public UserController(RestaurantDbContext context)
 {
 _context = context;
 }
 // 获取所有用户
 [HttpGet]
 public async Task>> GetUsers()
 {
 return await _context.Users.ToListAsync();
 }
 // 根据ID获取用户
 [HttpGet("{id}")]
 public async Task> GetUser(int id)
 {
 var user = await _context.Users.FindAsync(id);
 if (user == null)
 {
 return NotFound(); // 返回404
 }
 return user;
 }
 // 添加用户
 [HttpPost]
 public async Task> PostUser(User user)
 {
 _context.Users.Add(user);
 await _context.SaveChangesAsync();
 // 返回201 Created，同时包含新用户的URL
 return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user);
 }
 // 修改用户
 [HttpPut("{id}")]
 public async Task PutUser(int id, User user)
 {
 if (id != user.Id)
 {
 return BadRequest(); // ID不匹配，返回400
 }
 _context.Entry(user).State = EntityState.Modified;
 try
 {
 await _context.SaveChangesAsync();
 }
 catch (DbUpdateConcurrencyException)
 {
 if (!UserExists(id))
 {
 return NotFound();
 }
 else
 {
 throw;
 }
 }
 return NoContent(); // 返回204
 }
 // 删除用户
 [HttpDelete("{id}")]
 public async Task DeleteUser(int id)
 {
 var user = await _context.Users.FindAsync(id);
 if (user == null)
 {
 return NotFound();
 }
 _context.Users.Remove(user);
 await _context.SaveChangesAsync();
 return NoContent();
 }
 // 检查用户是否存在
 private bool UserExists(int id)
 {
 return _context.Users.Any(e => e.Id == id);
 }
}

这个模板的好处是“规范”：每个接口都用了对应的HTTP方法（Get、Post、Put、Delete），返回正确的状态码（比如404、201），还处理了并发异常——去年我帮客户写接口时，一开始没加CreatedAtAction，前端不知道怎么获取新用户的ID，后来加了这个方法，前端直接从响应头里拿URL，省了好多沟通成本。

.Net8 WebAPI部署：三种常用方式的实战对比

写好接口后，接下来是部署——这是很多开发者的“噩梦”：要么环境不一致，要么权限不够，要么访问不通。我 了三种常用的部署方式，每种都试过至少5次，帮你避掉90%的坑。

IIS是Windows服务器上的传统部署方式，适合内网项目（比如企业内部系统）。去年我帮一个制造业客户部署内网API时，用的就是IIS，步骤很固定：

① 发布项目：打开VS→右键项目→点击“发布”→选择“文件夹”→选一个发布路径（比如D:PublishRestaurantApi）→点击“发布”。VS会自动把项目编译成可执行文件和依赖项。

② 配置IIS：打开“Internet Information Services (IIS)管理器”→右键“网站”→点击“添加网站”→填写网站名称（比如“RestaurantApi”）→物理路径选刚才的发布路径→端口选8080（避免和其他网站冲突）→点击“确定”。

③ 调整应用程序池：找到刚才创建的网站→右键“应用程序池”→选择“基本设置”→把“.NET CLR版本”改成“无托管代码”（因为.Net Core是跨平台的，不需要Windows的CLR）→点击“确定”。

④ 设置权限：右键发布文件夹→点击“属性”→“安全”→“编辑”→“添加”→输入“IIS_IUSRS”→点击“检查名称”→确定→给“IIS_IUSRS”赋予“读取和执行”权限→保存。

部署完成后，打开浏览器输入http://localhost:8080/api/User，就能看到用户列表了。

坑提醒：我去年部署时忘改应用程序池的“.NET CLR版本”，结果报错“无法加载托管代码”；还有一次没给文件夹加权限，报500错误——这两个是IIS部署最常踩的坑，一定要记住。

如果你做的是跨平台项目（比如同时部署在Windows和Linux服务器），Docker绝对是神器——它能保证开发环境和生产环境完全一致。去年我帮客户做微服务项目时，用Docker解决了“本地能跑、服务器跑不通”的问题，步骤如下：

① 写Dockerfile：在项目根目录新建Dockerfile（没有后缀名），输入以下内容：

# 基础镜像：.NET 8运行时
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80 # 暴露80端口
构建镜像：.NET 8 SDK
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["RestaurantApi.csproj", "."] # 复制项目文件
RUN dotnet restore "./RestaurantApi.csproj" # 还原依赖
COPY . . # 复制所有文件
WORKDIR "/src/."
RUN dotnet build "RestaurantApi.csproj" -c Release -o /app/build # 编译项目
发布项目
FROM build AS publish
RUN dotnet publish "RestaurantApi.csproj" -c Release -o /app/publish # 发布到/app/publish
最终镜像：运行项目
FROM base AS final
WORKDIR /app
COPY from=publish /app/publish . # 从publish阶段复制发布文件
ENTRYPOINT ["dotnet", "RestaurantApi.dll"] # 启动命令

② 构建镜像：打开终端→进入项目根目录→输入docker build -t restaurantapi .→等待镜像构建完成。

③ 运行容器：输入docker run -d -p 8080:80 restaurantapi→回车。这个命令会把容器的80端口映射到主机的8080端口，这样就能通过http://localhost:8080访问API了。

坑提醒：我第一次构建镜像时，镜像大小超过2G——后来发现是COPY . .把bin、obj这些编译目录也拷进去了。解决办法是在项目根目录新建.dockerignore文件，输入：

bin/
obj/
node_modules/

这样Docker就会忽略这些目录，镜像大小能缩小到300M左右。

如果你做的是公网项目（比如面向用户的APP后端），云服务（比如Azure App Service、阿里云ECS）是最省心的选择——不用自己维护服务器，一键就能上线。去年我帮一个创业公司做电商API时，用的是Azure App Service，步骤超简单：

① 创建App Service：登录Azure portal→点击“创建资源”→搜索“App Service”→点击“创建”→填写订阅、资源组、名称（比如“RestaurantApi”）→发布方式选“代码”→运行时栈选“.NET 8”→操作系统选“Linux”（比Windows快）→点击“创建”。

② 发布项目：打开VS→右键项目→点击“发布”→选择“Azure App Service”→选择刚才创建的App Service→点击“发布”。VS会自动把项目上传到Azure，并启动服务。

③ 测试接口：打开Azure portal→找到刚才的App Service→复制“默认域名”（比如restaurantapi.azurewebsites.net）→在浏览器输入http://restaurantapi.azurewebsites.net/api/User，就能访问接口了。

坑提醒：我第一次用Azure部署时，选了Windows操作系统，结果启动时间要30秒——后来改成Linux，启动时间降到10秒，响应速度也快了一倍。

三种部署方式的对比：选适合自己的才是最好的

为了帮你快速选到适合的方式，我做了个对比表格：

<td style="border: 1

YUANLEISVIP

收藏 链接