znlgis 博客

GIS开发与技术分享

第二章:环境搭建与项目创建

目录

  1. 开发环境要求
  2. .NET SDK安装与配置
  3. 使用Furion项目模板创建项目
  4. 手动创建Furion项目
  5. 项目结构说明
  6. NuGet包管理与依赖说明
  7. 第一个Hello World接口
  8. Swagger API文档配置
  9. 运行与调试
  10. 常见搭建问题解决

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安装:

  1. 右键项目 → 管理NuGet程序包
  2. 搜索”Furion”
  3. 选择需要的包并点击安装

通过项目文件引用:

<!-- 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调试

  1. 打开解决方案文件(.sln
  2. 将Web.Entry项目设置为启动项目
  3. F5 启动调试 或 Ctrl+F5 无调试运行
  4. 在代码中设置断点进行调试

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的项目架构与核心设计,包括分层架构、启动配置、配置系统和模块化设计等内容。