Fastdotnet 插件开发:一键生成,快速上手

在现代化的软件开发中，插件化架构已经成为提升系统扩展性和维护性的关键技术方案。Fastdotnet 框架提供了强大的插件开发能力，而全新的 Fastdotnet.Plugin.CLI 工具更是让插件开发变得前所未有的简单和高效。

本文将详细介绍如何使用 CLI 工具快速创建插件项目，以及 Fastdotnet 插件系统的核心优势。

💡 为什么选择 Fastdotnet 插件开发？

✨ 核心优势

1. 快速启动
   
   ：通过 CLI 工具，只需一条命令即可生成完整的插件项目骨架
2. 前后端分离
   
   ：自动生成后端 API 和前端 Vue 项目结构
3. 标准化规范
   
   ：遵循统一的插件开发规范，确保代码质量
4. 热插拔支持
   
   ：插件可以动态加载和卸载，无需重启主程序
5. 完善的生命周期管理
   
   ：提供初始化、启动、服务等完整的生命周期钩子
6. 微前端集成
   
   ：前端采用微前端架构，支持独立开发和部署

🛠️ 安装与使用

第一步：安装 CLI 工具

从 NuGet 安装最新的 Fastdotnet.Plugin.CLI 工具：

dotnet tool install -g Fastdotnet.Plugin.CLI

验证安装是否成功：

fd-plugin --version

第二步：创建插件项目

CLI 工具提供两种创建方式，适合不同场景：

方式一：交互式模式（推荐新手）

fd-plugin

工具会引导你完成所有配置：

交互式插件项目创建向导

插件名称（英文，用于命名空间，例如：MyPlugin）: MyPlugin
插件显示名称（中文，例如：我的插件）: 我的插件
官网申请的 PluginId: 12345678901234567
插件描述: 这是一个示例插件
输出目录: .
是否包含前端项目？ Yes
是否生成 .sln 解决方案文件？ No

方式二：命令行模式（适合自动化）

fd-plugin create \
  --name MyPlugin \
  --plugin-id 12345678901234567 \
  --display-name "我的插件" \
  --description "这是一个示例插件" \
  --output ./plugins \
  --include-frontend \
  --include-sln false

📁 生成的项目结构

执行创建命令后，你将获得一个完整的项目结构：

MyPlugin/
├── Backend/                    # 后端项目
│   ├── MyPlugin.csproj         # 项目文件
│   ├── MyPluginPlugin.cs       # 插件入口类
│   ├── plugin.json             # 插件元数据
│   ├── Controllers/            # API 控制器
│   │   └── SampleController.cs # 示例控制器
│   ├── Dto/                    # 数据传输对象
│   ├── Initializers/           # 初始化器
│   │   └── FdMenuConfigInitializer.cs  # 菜单配置
│   └── Properties/
│       └── launchSettings.json
│
├── Frontend/                   # 前端项目（如果选择包含）
│   ├── MyPlugin.Admin/         # 管理端
│   │   ├── src/
│   │   │   ├── views/          # 页面组件
│   │   │   ├── router/         # 路由配置
│   │   │   └── main.ts         # 入口文件
│   │   ├── vite.config.ts      # Vite 配置
│   │   ├── micro-index.html    # 微前端入口
│   │   └── package.json
│   │
│   └── MyPlugin.App/           # 应用端
│       ├── src/
│       ├── vite.config.ts
│       ├── micro-index.html
│       └── package.json
│
└── publish/                    # 发布目录（构建后生成）
    └── {PluginId}/
        ├── dependencies/       # 后端 DLL
        ├── wwwroot/
        │   ├── admin/          # 管理端静态资源
        │   └── app/            # 应用端静态资源
        └── plugin.json

🔍 核心文件解析

1. plugin.json – 插件身份证

这是插件的元数据文件，定义了插件的基本信息：

{
"PluginId":"12345678901234567",
"Name":"MyPlugin",
"DisplayName":"我的插件",
"Version":"1.0.0",
"Description":"这是一个示例插件",
"Author":"Your Name",
"Website":"",
"MinHostVersion":"1.0.0",
"Enabled":true
}

关键点：

• PluginId
  
   必须从官网申请，保证全局唯一
• Version
  
   遵循语义化版本规范（Major.Minor.Patch）
• MinHostVersion
  
   指定兼容的最低宿主版本

2. MyPluginPlugin.cs – 插件入口

继承自 PluginBase 的核心类，管理插件的生命周期：

using Fastdotnet.Plugin.Contracts;

namespaceMyPlugin
{
publicclassMyPluginPlugin : PluginBase
    {
publicoverridestring PluginId => "12345678901234567";

publicoverridestring Name => "MyPlugin";

publicoverridestring Version => "1.0.0";

protectedoverrideasync Task OnInitializeAsync(IServiceProvider serviceProvider)
        {
// 插件初始化逻辑
awaitbase.OnInitializeAsync(serviceProvider);
        }

protectedoverrideasync Task OnStartAsync()
        {
// 插件启动逻辑
awaitbase.OnStartAsync();
        }

publicoverridevoidConfigureServices(ContainerBuilder builder)
        {
// 注册依赖注入服务
base.ConfigureServices(builder);
        }
    }
}

生命周期方法：

• OnInitializeAsync
  
  插件加载时调用，适合进行初始化配置
• OnStartAsync
  
  插件启动时调用，适合启动后台任务
• ConfigureServices
  
  注册服务到依赖注入容器

3. vite.config.ts – 前端构建配置

前端的 Vite 配置文件，支持热更新和微前端集成：

import { defineConfig } from'vite'
import vue from'@vitejs/plugin-vue'
import path from'path'

exportdefaultdefineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': path.resolve(__dirname, 'src')
    }
  },
server: {
port: 8099,  // 开发服务器端口
cors: true
  },
build: {
outDir: '../../publish/{PluginId}/wwwroot/admin',  // 构建输出目录
emptyOutDir: true
  }
})

🎯 开发流程

第一步：获取 Plugin ID

在开始开发之前，你需要从 Fastdotnet 官网申请唯一的 Plugin ID：

1. 访问 https://fastdotnet.top/marketplace
2. 注册/登录开发者账号
3. 进入”开发者中心”
4. 申请新的 Plugin ID
5. 记录 ID 并填入 plugin.json

第二步：恢复依赖

# 后端
cd Backend
dotnet restore

# 前端（如果包含）
cd ../Frontend/MyPlugin.Admin
pnpm install

cd ../MyPlugin.App
pnpm install

第三步：开始开发

后端开发：

• 添加控制器处理 API 请求
• 创建服务层实现业务逻辑
• 定义数据模型和 DTO
• 配置菜单和权限

前端开发：

• 开发页面组件
• 配置路由
• 调用后端 API
• 实现业务交互

第四步：构建与发布

# 构建后端
cd Backend
dotnet build

# 构建前端
cd ../Frontend/MyPlugin.Admin
pnpm build

cd ../MyPlugin.App
pnpm build

构建产物会自动输出到 publish/{PluginId}/ 目录，可以直接部署到 Fastdotnet 主程序中。

💡 最佳实践

1. 及时更新 CLI 工具

为确保创建的插件与最新版本的 Fastdotnet 框架兼容，建议在使用前始终更新 CLI 工具到最新版本：

dotnet tool update -g Fastdotnet.Plugin.CLI
fd-plugin --version  # 检查版本

为什么需要更新？

• 🔄 框架升级后，插件模板可能发生变化
• 🐛 修复已知的 Bug 和问题
• ✨ 新增功能和改进
• 🔒 安全性更新

2. 遵循语义化版本

插件版本号应遵循 Major.Minor.Patch 格式：

• Major
  
  : 不兼容的 API 修改
• Minor
  
  : 向后兼容的功能性新增
• Patch
  
  : 向后兼容的问题修正

3. 合理使用生命周期方法

• OnInitializeAsync
  
  适合进行一次性初始化，如数据库迁移、缓存预热
• OnStartAsync
  
  适合启动定时任务、消息监听器等
• ConfigureServices
  
  只负责服务注册，不要执行耗时操作

4. 前端微前端集成

前端项目采用微前端架构，确保：

• 使用 micro-index.html 作为入口
• 正确配置 vite.config.ts 中的构建输出路径
• 避免全局样式污染
• 合理使用路由前缀

❓ 常见问题

Q: 为什么要及时更新 CLI 工具？

A: Fastdotnet 框架会不断更新，插件模板也会随之变化。使用最新版本的 CLI 工具可以确保：

• ✅ 生成的插件与当前框架版本完全兼容
• ✅ 使用最新的最佳实践和代码规范
• ✅ 避免已知的 Bug 和问题
• ✅ 获得新功能和改进

建议：每次创建新插件前，先运行 dotnet tool update -g Fastdotnet.Plugin.CLI。

Q: Plugin ID 格式有什么要求？

A: Plugin ID 应该是小写字母、数字和连字符的组合，例如：my-plugin-123。但实际使用时，官网会分配一个数字 ID。

Q: 可以不包含前端项目吗？

A: 可以。在创建时使用 --include-frontend false 参数，或者在交互模式下选择”No”。

Q: 为什么默认不生成 .sln 文件？

A: 为了保持项目简洁。如果需要，可以在创建时指定 --include-sln true，或手动在 Visual Studio 中创建。

Q: 如何修改已创建项目的 Plugin ID？

A:

1. 修改 Backend/plugin.json 中的 PluginId
2. 修改 Backend/MyPluginPlugin.cs 中的 PluginId 属性
3. 重新构建项目

Q: 前端构建后文件在哪里？

A: 构建产物会自动输出到 publish/{PluginId}/wwwroot/admin/ 和 publish/{PluginId}/wwwroot/app/ 目录。

🌟 总结

Fastdotnet 插件开发体系为开发者提供了：

✅ 极简的入门体验：一条命令生成完整项目
✅ 标准化的开发流程：统一的规范和最佳实践
✅ 灵活的扩展能力：前后端分离，微前端集成
✅ 完善的生态支持：插件商城、文档、社区

无论你是经验丰富的开发者，还是刚接触插件开发的新手，Fastdotnet.Plugin.CLI 都能让你快速上手，专注于业务逻辑的实现，而不是繁琐的项目配置。