第二章:环境搭建与项目创建
目录
- 开发环境要求
- .NET SDK安装与配置
- 使用Furion项目模板创建项目
- 手动创建Furion项目
- 项目结构说明
- NuGet包管理与依赖说明
- 第一个Hello World接口
- Swagger API文档配置
- 运行与调试
- 常见搭建问题解决
1. 开发环境要求
1.1 硬件要求
| 配置项 | 最低要求 | 推荐配置 |
|---|---|---|
| 处理器 | 双核1.8GHz | 四核3.0GHz及以上 |
| 内存 | 4GB | 8GB及以上 |
| 硬盘 | 10GB可用空间 | SSD,20GB以上可用空间 |
| 网络 | 需要联网下载依赖 | 稳定的网络连接 |
1.2 软件要求
| 工具 | 版本要求 | 必要性 | 说明 |
|---|---|---|---|
| .NET SDK | 6.0 / 7.0 / 8.0+ | 必须 | Furion的运行基础 |
| Visual Studio 2022 | 17.4+ | 推荐 | 功能最全的IDE |
| Visual Studio Code | 最新版 | 可选 | 轻量级编辑器 |
| JetBrains Rider | 2023.1+ | 可选 | 跨平台IDE |
| Git | 2.x | 推荐 | 版本控制工具 |
| Postman / Apifox | 最新版 | 推荐 | API测试工具 |
1.3 操作系统支持
Furion基于ASP.NET Core,天然支持跨平台部署:
- Windows:Windows 10/11, Windows Server 2016+
- Linux:Ubuntu 18.04+, CentOS 7+, Debian 10+
- macOS:macOS 10.15+
2. .NET SDK安装与配置
2.1 下载.NET SDK
访问.NET官方下载页面获取最新SDK:
推荐安装.NET 8 SDK(LTS长期支持版本)。
2.2 Windows安装
下载安装程序后,双击运行,按照向导提示完成安装。安装完成后验证:
# 验证SDK安装
dotnet --version
# 查看已安装的SDK版本
dotnet --list-sdks
# 查看已安装的运行时版本
dotnet --list-runtimes
预期输出示例:
8.0.401
2.3 Linux安装
以Ubuntu为例:
# 添加Microsoft包源
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
# 安装.NET 8 SDK
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0
# 验证安装
dotnet --version
2.4 macOS安装
# 使用Homebrew安装
brew install dotnet-sdk
# 或下载官方安装包安装后验证
dotnet --version
2.5 配置NuGet源
对于国内用户,建议添加国内NuGet镜像源以加速包下载:
# 添加华为云NuGet镜像
dotnet nuget add source https://mirrors.huaweicloud.com/repository/nuget/v3/index.json -n huaweicloud
# 查看已配置的NuGet源
dotnet nuget list source
也可以编辑NuGet.Config文件:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
<add key="huaweicloud" value="https://mirrors.huaweicloud.com/repository/nuget/v3/index.json" />
</packageSources>
</configuration>
3. 使用Furion项目模板创建项目
3.1 安装Furion项目模板
Furion提供了官方的项目模板,可以通过dotnet new命令安装:
# 安装Furion API项目模板
dotnet new install Furion.Template.Api
# 安装Furion Razor Pages项目模板
dotnet new install Furion.Template.Razor
# 安装Furion MVC项目模板
dotnet new install Furion.Template.Mvc
# 安装Furion Blazor Server项目模板
dotnet new install Furion.Template.Blazor
# 安装Furion Blazor WASM项目模板
dotnet new install Furion.Template.BlazorWithWebApi
# 查看已安装的模板
dotnet new list furion
3.2 使用模板创建项目
# 创建API项目(最常用)
dotnet new furionapi -n MyFurionApp
# 创建MVC项目
dotnet new furionmvc -n MyFurionMvcApp
# 创建Razor Pages项目
dotnet new furionrazor -n MyFurionRazorApp
# 创建Blazor Server项目
dotnet new furionblazor -n MyFurionBlazorApp
3.3 模板生成的项目结构
以furionapi模板为例,生成的解决方案结构如下:
MyFurionApp/
├── MyFurionApp.sln # 解决方案文件
├── MyFurionApp.Application/ # 应用层
│ ├── MyFurionApp.Application.csproj
│ └── ...
├── MyFurionApp.Core/ # 核心层
│ ├── MyFurionApp.Core.csproj
│ └── ...
├── MyFurionApp.EntityFramework.Core/ # EF Core层
│ ├── MyFurionApp.EntityFramework.Core.csproj
│ └── ...
├── MyFurionApp.Web.Core/ # Web核心层
│ ├── MyFurionApp.Web.Core.csproj
│ └── ...
└── MyFurionApp.Web.Entry/ # Web入口层
├── MyFurionApp.Web.Entry.csproj
├── Program.cs
└── appsettings.json
3.4 运行模板项目
# 进入项目目录
cd MyFurionApp
# 还原NuGet包
dotnet restore
# 运行项目
dotnet run --project MyFurionApp.Web.Entry
运行成功后,访问 https://localhost:5001 即可看到Swagger文档页面。
4. 手动创建Furion项目
4.1 创建空项目
如果不想使用模板,也可以从空项目开始手动集成Furion:
# 创建解决方案
dotnet new sln -n MyApp
# 创建Web API项目
dotnet new webapi -n MyApp.Web --no-https
# 将项目添加到解决方案
dotnet sln MyApp.sln add MyApp.Web/MyApp.Web.csproj
4.2 添加Furion NuGet包
cd MyApp.Web
# 添加Furion完整包(含EF Core)
dotnet add package Furion
# 或者添加纯净版(不含EF Core)
# dotnet add package Furion.Pure
4.3 配置Furion
修改Program.cs文件,注入Furion服务:
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// 注入Furion
builder.Inject();
builder.Services.AddControllers()
.AddInject(); // 添加Furion增强
var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
// 使用Furion中间件
app.UseInject(string.Empty);
app.Run();
4.4 创建Startup类(可选)
Furion支持使用独立的Startup类来组织服务配置:
// Startup.cs
using Furion;
namespace MyApp.Web;
public class Startup : AppStartup
{
public void ConfigureServices(IServiceCollection services)
{
// 在这里配置服务
services.AddControllers().AddInject();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// 在这里配置中间件管道
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
app.UseInject(string.Empty);
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
}
对应的Program.cs可以简化为:
// Program.cs
var builder = WebApplication.CreateBuilder(args).Inject();
var app = builder.Build();
app.Run();
4.5 添加第一个服务类
// Services/HelloService.cs
using Furion.DynamicApiController;
namespace MyApp.Web.Services;
/// <summary>
/// Hello服务 - 自动生成API接口
/// </summary>
public class HelloService : IDynamicApiController
{
/// <summary>
/// 获取问候语
/// </summary>
/// <param name="name">姓名</param>
/// <returns>问候信息</returns>
public string SayHello(string name)
{
return $"你好,{name}!欢迎使用Furion框架。";
}
}
5. 项目结构说明
5.1 推荐的多层项目结构
Furion推荐使用分层架构来组织项目代码:
MyApp/
├── MyApp.sln # 解决方案文件
│
├── MyApp.Core/ # 核心层
│ ├── Entities/ # 实体类
│ │ ├── User.cs
│ │ └── Role.cs
│ ├── Enums/ # 枚举定义
│ ├── Consts/ # 常量定义
│ └── MyApp.Core.csproj
│
├── MyApp.Application/ # 应用层
│ ├── Services/ # 应用服务
│ │ ├── UserService.cs
│ │ └── RoleService.cs
│ ├── Dtos/ # 数据传输对象
│ │ ├── UserDto.cs
│ │ └── RoleDto.cs
│ └── MyApp.Application.csproj
│
├── MyApp.EntityFramework.Core/ # EF Core层
│ ├── DbContexts/ # 数据库上下文
│ │ └── DefaultDbContext.cs
│ ├── Migrations/ # 数据库迁移
│ └── MyApp.EntityFramework.Core.csproj
│
├── MyApp.Web.Core/ # Web核心层
│ ├── Startup.cs # 启动配置
│ ├── Handlers/ # 处理器
│ └── MyApp.Web.Core.csproj
│
└── MyApp.Web.Entry/ # Web入口层
├── Program.cs # 程序入口
├── appsettings.json # 配置文件
├── appsettings.Development.json # 开发环境配置
└── MyApp.Web.Entry.csproj
5.2 各层职责说明
| 层 | 项目名 | 职责 | 引用关系 |
|---|---|---|---|
| 核心层 | MyApp.Core | 定义实体、枚举、接口、常量 | 无依赖 |
| 应用层 | MyApp.Application | 业务逻辑、服务实现、DTO | 引用Core层 |
| EF Core层 | MyApp.EntityFramework.Core | 数据库上下文、迁移、种子数据 | 引用Core层 |
| Web核心层 | MyApp.Web.Core | 启动配置、过滤器、中间件 | 引用Application层和EF Core层 |
| Web入口层 | MyApp.Web.Entry | 程序入口、运行配置 | 引用Web.Core层 |
5.3 项目引用关系图
MyApp.Web.Entry
└── MyApp.Web.Core
├── MyApp.Application
│ └── MyApp.Core
└── MyApp.EntityFramework.Core
└── MyApp.Core
5.4 简单项目结构
对于小型项目,可以使用单项目结构:
MyApp/
├── MyApp.csproj
├── Program.cs
├── appsettings.json
├── Entities/
├── Services/
├── Dtos/
└── Data/
└── AppDbContext.cs
6. NuGet包管理与依赖说明
6.1 Furion核心包
| 包名 | 说明 | 适用场景 |
|---|---|---|
Furion |
完整版,包含EF Core集成 | 需要使用EF Core的项目 |
Furion.Pure |
纯净版,不包含EF Core | 使用其他ORM(如SqlSugar、Dapper)的项目 |
6.2 Furion扩展包
| 包名 | 说明 |
|---|---|
Furion.Extras.Authentication.JwtBearer |
JWT认证扩展 |
Furion.Extras.DatabaseAccessor.SqlSugar |
SqlSugar集成扩展 |
Furion.Extras.DatabaseAccessor.Dapper |
Dapper集成扩展 |
Furion.Extras.DatabaseAccessor.MongoDB |
MongoDB集成扩展 |
Furion.Extras.Logging.Serilog |
Serilog日志集成 |
Furion.Extras.ObjectMapper.Mapster |
Mapster对象映射扩展 |
Furion.Extras.DependencyModel.CodeAnalysis |
代码分析扩展 |
6.3 安装NuGet包
使用命令行安装:
# 安装核心包
dotnet add package Furion
# 安装指定版本
dotnet add package Furion --version 4.9.3.5
# 安装扩展包
dotnet add package Furion.Extras.Authentication.JwtBearer
使用Visual Studio安装:
- 右键项目 → 管理NuGet程序包
- 搜索”Furion”
- 选择需要的包并点击安装
通过项目文件引用:
<!-- MyApp.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Furion" Version="4.9.*" />
<PackageReference Include="Furion.Extras.Authentication.JwtBearer" Version="4.9.*" />
<PackageReference Include="Furion.Extras.ObjectMapper.Mapster" Version="4.9.*" />
</ItemGroup>
</Project>
6.4 版本策略
建议使用通配符版本号来自动获取最新的补丁版本:
<!-- 推荐:自动获取4.9.x的最新版本 -->
<PackageReference Include="Furion" Version="4.9.*" />
<!-- 固定版本:用于生产环境 -->
<PackageReference Include="Furion" Version="4.9.3.5" />
7. 第一个Hello World接口
7.1 创建完整的Hello World项目
按照以下步骤创建你的第一个Furion API项目:
步骤一:创建项目
dotnet new webapi -n HelloFurion --no-https
cd HelloFurion
dotnet add package Furion
步骤二:修改Program.cs
// Program.cs
using Furion;
var builder = WebApplication.CreateBuilder(args).Inject();
builder.Services.AddControllers().AddInject();
var app = builder.Build();
app.UseInject(string.Empty);
app.MapControllers();
app.Run();
步骤三:创建服务类
// Services/HelloService.cs
using Furion.DynamicApiController;
namespace HelloFurion.Services;
/// <summary>
/// Hello World 服务
/// </summary>
public class HelloService : IDynamicApiController
{
/// <summary>
/// 获取问候语
/// </summary>
/// <returns>返回Hello World</returns>
public string GetHello()
{
return "Hello, Furion!";
}
/// <summary>
/// 个性化问候
/// </summary>
/// <param name="name">您的姓名</param>
/// <returns>个性化问候语</returns>
public string GetGreeting(string name)
{
return $"你好,{name}!欢迎使用Furion框架开发。";
}
/// <summary>
/// 获取当前时间
/// </summary>
/// <returns>服务器当前时间</returns>
public object GetCurrentTime()
{
return new
{
Time = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),
TimeZone = TimeZoneInfo.Local.DisplayName,
Framework = "Furion"
};
}
}
步骤四:运行项目
dotnet run
步骤五:测试接口
项目启动后,访问 http://localhost:5000 即可看到Swagger文档页面,自动生成了以下接口:
| HTTP方法 | URL | 说明 |
|---|---|---|
| GET | /api/hello/hello | 获取Hello World |
| GET | /api/hello/greeting?name=张三 | 个性化问候 |
| GET | /api/hello/current-time | 获取当前时间 |
7.2 使用curl测试
# 测试Hello接口
curl http://localhost:5000/api/hello/hello
# 输出: "Hello, Furion!"
# 测试问候接口
curl "http://localhost:5000/api/hello/greeting?name=张三"
# 输出: "你好,张三!欢迎使用Furion框架开发。"
# 测试当前时间
curl http://localhost:5000/api/hello/current-time
# 输出: {"time":"2024-01-15 14:30:00","timeZone":"(UTC+08:00) 中国标准时间","framework":"Furion"}
8. Swagger API文档配置
8.1 默认Swagger配置
Furion内置了Swagger支持,通过AddInject()和UseInject()自动配置。默认情况下,Swagger文档可通过根路径访问。
8.2 自定义Swagger配置
在appsettings.json中自定义Swagger选项:
{
"SpecificationDocumentSettings": {
"DocumentTitle": "我的API文档",
"DefaultGroupName": "Default",
"FormatAsV2": false,
"DocExpansionState": "List",
"XmlComments": true,
"GroupOpenApiInfos": [
{
"Group": "Default",
"Title": "默认分组",
"Description": "默认接口分组",
"Version": "v1.0"
},
{
"Group": "System",
"Title": "系统管理",
"Description": "系统管理相关接口",
"Version": "v1.0"
}
],
"EnableAuthorized": true,
"SecurityDefinitions": [
{
"Id": "Bearer",
"Type": "Http",
"Name": "Authorization",
"Description": "JWT授权。在下方输入框中输入Token",
"BearerFormat": "JWT",
"Scheme": "bearer",
"In": "Header"
}
]
}
}
8.3 启用XML注释
在项目文件中启用XML文档生成:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
8.4 接口分组示例
using Furion.DynamicApiController;
using Microsoft.AspNetCore.Mvc;
namespace MyApp.Services;
/// <summary>
/// 用户管理服务
/// </summary>
[ApiDescriptionSettings("System", Name = "User", Order = 1)]
public class UserService : IDynamicApiController
{
/// <summary>
/// 获取用户列表
/// </summary>
[ApiDescriptionSettings(Description = "分页获取用户列表")]
public List<string> GetUsers()
{
return new List<string> { "张三", "李四", "王五" };
}
}
/// <summary>
/// 产品管理服务
/// </summary>
[ApiDescriptionSettings("Business", Name = "Product", Order = 2)]
public class ProductService : IDynamicApiController
{
/// <summary>
/// 获取产品列表
/// </summary>
public List<string> GetProducts()
{
return new List<string> { "产品A", "产品B", "产品C" };
}
}
9. 运行与调试
9.1 使用命令行运行
# 开发模式运行
dotnet run
# 指定环境运行
dotnet run --environment Development
dotnet run --environment Production
# 指定端口运行
dotnet run --urls "http://localhost:8080"
# 热重载运行(代码修改自动重启)
dotnet watch run
9.2 使用Visual Studio调试
- 打开解决方案文件(
.sln) - 将Web.Entry项目设置为启动项目
- 按
F5启动调试 或Ctrl+F5无调试运行 - 在代码中设置断点进行调试
launchSettings.json配置示例:
{
"profiles": {
"MyApp.Web.Entry": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"launchUrl": "",
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
9.3 使用VS Code调试
创建.vscode/launch.json文件:
{
"version": "0.2.0",
"configurations": [
{
"name": "启动Furion项目",
"type": "coreclr",
"request": "launch",
"preLaunchTask": "build",
"program": "${workspaceFolder}/MyApp.Web.Entry/bin/Debug/net8.0/MyApp.Web.Entry.dll",
"args": [],
"cwd": "${workspaceFolder}/MyApp.Web.Entry",
"console": "internalConsole",
"stopAtEntry": false,
"env": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
]
}
9.4 常用调试技巧
查看日志输出:
using Furion.DynamicApiController;
using Microsoft.Extensions.Logging;
public class DebugService : IDynamicApiController
{
private readonly ILogger<DebugService> _logger;
public DebugService(ILogger<DebugService> logger)
{
_logger = logger;
}
public string GetDebugInfo()
{
_logger.LogInformation("DebugInfo接口被调用,时间:{Time}", DateTime.Now);
_logger.LogDebug("这是调试级别的日志");
return "调试信息已记录到日志";
}
}
配置开发环境日志级别:
// appsettings.Development.json
{
"Logging": {
"LogLevel": {
"Default": "Debug",
"Microsoft.AspNetCore": "Warning",
"Microsoft.EntityFrameworkCore": "Information"
}
}
}
10. 常见搭建问题解决
10.1 问题排查清单
| 序号 | 问题 | 原因 | 解决方案 |
|---|---|---|---|
| 1 | 无法找到Furion包 | NuGet源配置错误 | 确认nuget.org源已添加 |
| 2 | 版本不兼容 | SDK版本与Furion版本不匹配 | 检查.NET SDK版本 |
| 3 | Swagger页面空白 | 未正确注入Furion | 检查AddInject()和UseInject()配置 |
| 4 | 接口未自动生成 | 服务类未实现IDynamicApiController | 确认实现了正确的接口 |
| 5 | 端口被占用 | 其他程序占用了默认端口 | 修改launchSettings.json中的端口 |
| 6 | XML注释不显示 | 未启用XML文档生成 | 在csproj中添加GenerateDocumentationFile |
10.2 常见错误及解决
错误1:找不到Furion命名空间
error CS0246: The type or namespace name 'Furion' could not be found
解决方案:
# 确保已安装Furion包
dotnet add package Furion
# 还原包
dotnet restore
错误2:Inject方法不存在
'WebApplicationBuilder' does not contain a definition for 'Inject'
解决方案:确保在文件顶部添加了正确的using语句:
using Furion; // 必须添加此引用
错误3:运行时端口冲突
System.IO.IOException: Failed to bind to address http://localhost:5000
解决方案:
# 方法1:使用不同端口
dotnet run --urls "http://localhost:8080"
# 方法2:查找并关闭占用端口的进程(Linux/macOS)
lsof -i :5000
kill -9 <PID>
# 方法3:修改launchSettings.json中的applicationUrl
错误4:Swagger页面报错
如果Swagger页面出现错误,通常是由于XML注释格式不正确或接口定义有问题:
// 确保所有公开方法都有XML注释
/// <summary>
/// 方法描述
/// </summary>
/// <param name="id">参数描述</param>
/// <returns>返回值描述</returns>
public string GetById(int id)
{
return $"Item {id}";
}
10.3 开发环境检查脚本
可以创建一个检查脚本来验证开发环境是否正确配置:
#!/bin/bash
echo "=== Furion开发环境检查 ==="
echo "1. 检查.NET SDK..."
dotnet --version && echo " ✅ .NET SDK 已安装" || echo " ❌ .NET SDK 未安装"
echo "2. 检查NuGet源..."
dotnet nuget list source
echo "3. 检查项目包..."
dotnet list package | grep Furion && echo " ✅ Furion包已安装" || echo " ❌ Furion包未安装"
echo "4. 编译检查..."
dotnet build --no-restore && echo " ✅ 编译成功" || echo " ❌ 编译失败"
echo "=== 检查完成 ==="
总结
本章详细介绍了Furion开发环境的搭建过程,包括.NET SDK的安装、Furion项目模板的使用、手动创建项目的方法、项目结构说明以及Swagger文档的配置。通过创建第一个Hello World接口,你已经成功运行了一个基于Furion的Web API项目。
关键要点:
- 推荐使用.NET 8 LTS版本进行Furion开发
- 使用项目模板可以快速创建标准化的项目结构
Inject()和AddInject()是Furion集成的核心方法IDynamicApiController接口是动态WebAPI的关键- 遇到问题时先查看日志输出和错误信息
下一章预告:第三章将深入介绍Furion的项目架构与核心设计,包括分层架构、启动配置、配置系统和模块化设计等内容。