apeart / paste-apeart

104 提交 1 分支 0 标签

文件列表 16 项

文件内容 apeart.md 17 KB 8772 字符

# 为什么说PasteApeart框架敢说是敏捷开发天花板，看这篇介绍就够了！

> 一个让你彻底告别“代码该写在哪”灵魂拷问的框架，从个人项目到500人团队，从表单配置到核心业务，它比你想象的更强大。

## PasteApeart的由来

在AI编程助手盛行的今天，有人说“10分钟就能生成一个模块”，那我们为什么还需要一个开发框架？

因为AI能生成代码，但**生成不了架构**。它能在10秒内给你100种“怎么写”的方案，但永远没法告诉你——**这一段业务逻辑，整个团队应该约定写在哪里**。

PasteApeart源于**PasteForm**框架的升级。PasteForm的核心思想是**“All in DTO”**——通过定义DTO（数据传输对象）及其特性（Attribute），后端直接驱动前端的UI渲染和交互逻辑。

而PasteApeart正是PasteForm的**完全体升级版**。它不仅仅是把“All in DTO”的思想发挥到极致，更引入了全新的**“All in Handler”**架构设计。简单说，它不是一个功能大礼包，而是一套**基于编译器物理约束的、极简的团队开发公约**。

## 先来一个热身需求：添加角色名称查询

假设系统中有一个**角色信息(GradeInfo)**，原本只有关键字查询功能。现在需求来了：**添加按名称查询角色**。

用PasteApeart怎么做？**只要两步**：

### 第一步：在查询DTO中添加一个字段

```csharp
///<summary>
/// 查询
///</summary>
[Description("查询")]
public class InputQueryGradeInfo : InputSearchBase
{
    ///<summary>
    ///名称
    ///</summary>
    [MaxLength(16)]
    [Description("名称 基于名称查询")]
    public string Name { get; set; }
}
```

### 第二步：重新生成，一键部署

打开10几秒钟后，刷新页面——

**搜索框里已经自动出现了“名称”这个查询条件**。输入名称，点击查询，结果就出来了。

**整个过程，后端业务代码零改动，前端零改动**。这就是PasteApeart的威力。

## 再进阶：权限绑定，一个关联表的复杂操作

如果需求是**为角色绑定权限**，这是一个典型的多对多关联操作。传统做法需要建关联表、写Service、写Controller、改前端页面……至少半天起步。

PasteApeart怎么做？

1. 创建关联实体`GradeRole`
2. 在实体DTO上添加`[PasteExtendBind]`特性
3. 在角色列表页加一个“绑定权限”的菜单按钮
4. 重新生成，一键部署

**完事了**。打开角色列表，点击“绑定权限”，弹出权限列表页面，勾选需要的权限，保存。关联数据自动写入`GradeRole`表，再次打开时已勾选的权限自动显示为选中状态。

**是不是很简单！**

你会发现，如果你要为一个字段配置可查询，**只要在查询的Model中添加这个字段即可**，管理端代码是不用动的——这就是PasteApeart框架的优雅所在！

## 超出预期：用表单配置替代富文本编辑器

很多人看到这里，可能觉得“这不就是个CRUD工具吗”？其实**PasteApeart的应用场景远比CRUD更广**。

来看一个常见场景：

> 很多系统有个“系统配置”页面，普通用户需要编辑JSON配置或XML文件。程序员图省事，直接扔一个富文本编辑器让用户自己编辑配置文件。

这个做法有什么问题？

- 用户容易写错格式，一个逗号、一个引号就导致整个系统崩溃
- 没有字段说明，用户不知道每个配置项是什么意思
- 没有校验，用户可以输入任何非法值
- 用户体验极差，普通用户看到代码就发怵

**如果用PasteApeart呢？**

你只需要定义一个配置项的DTO：

```csharp
///<summary>
/// 系统配置
///</summary>
[Description("系统配置")]
public class SystemConfigDto
{
    ///<summary>
    /// 网站名称
    ///</summary>
    [Required]
    [MaxLength(50)]
    [Description("网站名称")]
    public string SiteName { get; set; }

///<summary>
    /// 最大上传文件大小(MB)
    ///</summary>
    [Required]
    [Range(1, 100)]
    [Description("最大上传文件大小(MB)")]
    public int MaxFileSize { get; set; }

///<summary>
    /// 是否开启注册
    ///</summary>
    [Description("是否开启注册")]
    public bool EnableRegister { get; set; }

///<summary>
    /// 邮件服务器地址
    ///</summary>
    [Required]
    [EmailAddress]
    [Description("邮件服务器地址")]
    public string EmailHost { get; set; }
}
```

然后呢？**PasteApeart自动帮你渲染出一个表单页面**：

- 网站名称 → 文本框，必填，最多50字
- 最大上传文件大小 → 数字输入框，范围1-100
- 是否开启注册 → 开关组件
- 邮件服务器地址 → 文本框，自动校验邮箱格式

**用户看到的是友好的表单，而不是一堆看不懂的代码。** 字段有说明、有校验、有格式约束，用户永远不可能输入非法值。

**这就是PasteApeart的价值——不只是给程序员用的CRUD框架，更是让终端用户也能安全、优雅地操作数据的工具。**

## 现有框架之痛

先别急着看框架介绍，先看看你团队里是不是经常发生下面这些事：

### 那些“为了接口而接口”的框架

有些框架，官方明明有现成的解决方案，偏要自己再封装一层。拿`IRepository`来说，市面上就没有一个框架的仓储实现是真正合格的。要么过度设计，要么绑定死某一种ORM，换数据库的时候欲哭无泪。

### 概念轰炸型框架

先让你学20个新概念：聚合根、值对象、规约模式、工作单元、领域服务、应用服务……学完了，“这段代码到底写在哪？”这个问题，团队里3个老员工能给出3个不同的答案。

### 项目爆炸型框架

号称“模块化”，一个解决方案拆成20个子项目。结果写一个普通的“订单创建”接口，需要引用12个其他项目。引用关系比蜘蛛网还乱，新人加一个功能要先研究半小时“我这个场景应该引用哪个项目的哪个接口？”

### 异步任务混乱型框架

一个“订单30分钟未支付自动取消”的需求，项目里共存了三种实现：有人用Hangfire、有人用BackgroundService轮询、有人用RabbitMQ死信交换机。新人想加个类似功能直接懵了：“我应该学哪套？”

如果你和你的团队也正被这些问题折磨，那么PasteApeart或许就是你一直在找的解药。

## PasteApeart的核心概念

PasteApeart有两个核心理念：

### All in DTO

**DTO（数据传输对象）是后端控制前端的唯一入口**。字段是否显示、是否可搜索、是输入框还是下拉框、是图片上传还是开关——全部通过DTO上的特性（Attribute）来控制。

这意味着什么？**前端只需要写一套通用组件**，剩下的所有页面逻辑都由后端DTO驱动。新增表、修改字段、调整UI顺序——前端代码一行都不用改。

### All in Handler

这是PasteApeart的灵魂。**所有跨表的、复杂的业务规则都写在Handler层**。Application只做单表CRUD的薄协调层，Host只做视图接口的路由入口。

真正的业务逻辑——下单扣库存、支付加积分、发货单生成——**100%集中在Handler里**。6种宿主（HTTP、MQ、定时任务、单元测试、控制台工具）全部复用同一份Handler代码，永远只维护一份。

## PasteApeart的组成

很多人第一次看到PasteApeart的模板项目，会有点“失望”——这也太简单了？解决方案里就**6个子项目**：

```
PasteApeart.Solution
├── 01. Application.Contracts （纯契约层：DTO + 接口定义，0依赖）
├── 02. Domain （纯实体/枚举，0逻辑）
├── 03. EntityFramework （DbContext + EF配置，仅此而已）
├── 04. Handler （★ 核心：业务规则聚合层 + 框架内核）
├── 05. Application （单表CRUD AppService，薄协调层）
└── 06. HttpApi.Host （Controller + 视图接口 + 启动入口）
```

**没错，6个子项目，比那些20个子项目的框架少了2/3。**

但最让人震惊的是它的**引用关系——一条直线，画不出一个环**：

```
Application.Contracts（0依赖，纯协议中心）
       ▲
       │
       ├────────────────┘
       ▼
Domain ◄────── Handler ──────► EntityFramework
       ▲          ▲
       │          │
       └──────── Application（只做单表CRUD）
       │
       └──────────────── Host（入口+视图接口）
```

**没有左右横跳的横向引用，没有交叉缠绕的蛛网依赖。**

一个新人只要看一眼这张图，永远不会问出“我能不能在Handler里调AppService的方法？”这种问题——因为Handler项目根本不引用Application项目，你想写？**编译期直接红波浪报错**，连提交都提交不了。

这就是PasteApeart和其他框架最本质的区别：

> **其他框架的“约定”是文档里的君子协定，写混了也没人管你。**
> **PasteApeart的“约定”是编译器的物理硬约束，写混了根本编译不过。**

## PasteApeart的核心优势

### 1. 新手5分钟就可以上手

我做了一个真实实验：招了一个刚毕业半年、只会写基础ASP.NET Core WebApi的新人，**不让他看任何文档，只让他看现有代码结构和1页A4纸的“代码写在哪里”对照表**。

结果是：**下午5点下班前，他独立写完了“商品分类管理”“商品品牌管理”“商品标签管理”3个完整模块**，包括CRUD接口、元数据接口、多层级路径算法、重复校验。

他是怎么做到的？因为PasteApeart的“约定对照表”，一页A4纸就能写完：

| 你要做的事 | 应该写在哪 | 备注 |
|---|---|---|
| **写一张表的CRUD接口** | → `Application/xxxAppService.cs` | 继承`DefaultAppService`，一行代码不用写就有9个接口 |
| **写跨N张表的业务规则** | → `Handler/modelhandler/xxxHandler.cs` | 只写业务逻辑，6种宿主随便调用 |
| **写异步/延迟/排重的任务** | → 定义Event + 实现IEventHandler | 延迟填`ExpireSecond`，排重填`MutexKey` |
| **写前端需要的跨表聚合查询** | → `HttpApi.Host/Controllers/xxxController.cs` | 视图接口，不污染Application层 |

### 2. 约定大于配置

PasteApeart信奉“约定大于配置”，但它的“约定”是**编译器的物理硬约束**。你不需要写一堆配置文件，只需要遵循项目结构和命名规范，框架自动帮你完成依赖注入、路由映射、元数据生成。

### 3. 高度灵活，不影响业务代码

这是PasteApeart最难得的品质——**所有模块都是“最薄的兜底 + 随时可以替换”**：

- **ORM可换**：EF Core / FreeSQL / Linq2DB，想换哪个换哪个，Handler里的业务代码0改动
- **数据库一行切换**：SqlServer / PostgreSQL / SQLite / 达梦 / 人大金仓，一行配置切换，其他代码不用动
- **前端全兼容**：Vue 3 / Vue 2 / React / Angular / Blazor，只要实现一套“解析元数据模型的通用渲染器”，所有业务实体0前端代码

### 4. 从个人项目到500人团队都适用

PasteApeart不是一个小众玩具，它的适用范围远比想象中广：

- **个人项目/小团队（2-5人）**：快速出活，一个人顶三个人，一周搭好管理后台
- **中型团队（10-50人）**：约定统一代码风格，新人一天上手，CodeReview工作量减少70%
- **大型团队（100-500人）**：物理硬约束保证架构不腐化，6个子项目的依赖关系一目了然，无论来多少人、走多少人，代码永远待在它该待的地方

特别值得一提的是**大型团队中的“配置管理”场景**：

很多大型系统有大量的配置项——系统参数、业务规则、审批流程配置、字段映射配置等。传统做法要么让开发人员写死在代码里（改一次发一次版），要么放数据库里配一个富文本编辑器让业务人员写JSON。

PasteApeart的DTO表单驱动模式，让**配置管理变成一个安全、优雅、受限的编辑体验**：

```csharp
// 审批流程配置 —— 普通业务人员也能安全操作
public class ApprovalConfigDto
{
    [Required]
    [Description("审批人")]
    public int ApproverId { get; set; }

[Required]
    [Range(0, 10)]
    [Description("审批层级")]
    public int Level { get; set; }

[Required]
    [Description("超时天数")]
    public int TimeoutDays { get; set; }
}
```

业务人员打开页面看到的是带说明、带校验、带下拉选择的表单，而不是一堆需要手动编辑的代码。**既保证了数据安全，又降低了操作门槛**。

### 5. 输出的是一个思想，可用其他语言实现

PasteApeart输出的核心是一个**思想**——All in DTO + All in Handler的分层架构，以及通过元数据模型驱动前端的模式。

这套思想完全可以用Java（Spring Boot + 注解）、Go（Gin + 结构体tag）、Node（NestJS + 装饰器）实现。**没有任何.NET特有的绑定**。

甚至你可以做**渐进式引入**：第1个月只引入“DTO元数据驱动”，第2个月引入“AutoAPI自动生成Controller”，第3个月引入Handler层——**不用推倒重来，哪块好用先引入哪块**。

## 关于PasteApeart的一些思考

### 不适用的场景

任何框架都有它的边界。PasteApeart也不是万能的：

❌ **不适合的场景**：
1. **不是标准业务系统**：比如游戏服务器、实时音视频、流式计算——这些场景PasteApeart的约定帮不上什么忙
2. **极度追求性能的底层系统**：反射和元数据驱动有一定开销，虽然对管理后台来说完全可以接受

✅ **最适合的场景**（90%的国内中小团队项目，以及大型项目中的管理/配置部分）：
1. **团队规模不限**：从1个人到500人都适用，只是适用的模块不同
2. **项目类型是标准业务系统**：管理后台、ERP、CRM、OA、电商后台、CMS
3. **系统中存在大量配置/参数管理需求**：用DTO表单替代富文本编辑器，让业务人员安全操作
4. **不想被任何技术栈绑架**：以后可能换数据库、换ORM、换前端

### 自定义与扩展

PasteApeart目前的管理端是基于HTML+JS实现的。由于后端可以直接控制前端的渲染，有些地方后端可以直接输出标签内容（比如表格中的按钮、状态标签等），灵活性非常高。

关于**权限控制**：支持通过`[RoleAttribute]`在接口层面做权限过滤，也支持在菜单按钮上配置权限码（`btnCode`），实现按钮级别的权限控制。

关于**自定义按钮**：框架自动提供新增、编辑、删除、详情等默认操作按钮。你也可以通过`[PasteButton]`特性自定义按钮，比如“备份”“恢复”等业务操作。

关于**条件显示**：支持`[PasteIfMenu]`根据数据条件动态显示按钮。比如只有状态为“待审核”的订单才显示“审核”按钮。

### 如何引入

最快捷的方式是参考官方提供的案例项目：

- **案例源码**：[https://gitee.com/pastecode/paste-template](https://gitee.com/pastecode/paste-template)
- **PasteBuilder工具**：可视化配置表结构，一键生成Entity + 5种DTO + AppService骨架
- **官方文档**：[https://soft.pastecode.cn/doc/](https://soft.pastecode.cn/doc/)

也可以先下载案例项目运行起来，感受一下“3个页面管100张表”的体验，再决定是否在自己的项目中引入。

## 开始使用PasteApeart

如果你想快速开始，可以参考以下步骤：

1. **下载案例项目**：从Gitee克隆PasteTemplate项目
2. **运行起来**：配置数据库连接，运行项目，打开管理端页面
3. **体验CRUD**：尝试新增一个模块，感受“改DTO驱动前端”的开发模式
4. **使用PasteBuilder**：安装配套的代码生成器插件，体验可视化生成代码
5. **阅读文档**：了解各个特性的详细用法

## 结语：好的框架，应该让你专注于业务

我用了18年各种各样的.NET框架，从最开始对“概念越多越先进、项目越多越专业”的迷信，到现在终于明白一件事：

> **好的框架，应该是用完之后，你根本想不起来它的存在。**

你不会每天想着“我要符合框架的规范”“我要用框架的高级功能”。你只会每天想着“今天的业务规则是什么”“这个用户的需求怎么实现”，然后按照框架给你的对照表，把代码写到它该写的地方，剩下的框架全替你兜了。

PasteApeart就是这样的框架：
- 它没给你100种写代码的方式，只给你1种约定好的、大家都一样的方式
- 它没给你20个项目假装架构先进，只给你6个子项目、引用方向一条直线
- 它没给你20个新概念让新人学半个月，只给你1页A4纸的对照表、新人一天就能上手
- 它不仅仅用于CRUD，更让表单配置、参数管理变得安全优雅，从个人项目到500人团队都能找到适用场景

如果你也受够了“20个子项目乱引用、新人入职三周才产出、异步逻辑复制5份、改Bug翻20个文件夹”的日子——

**试试PasteApeart，它不会让你觉得“哇好酷”，但会让你和你的团队，第一次觉得“写业务代码，原来可以这么清爽。”**

---

**项目地址**：[https://gitee.com/pastecode/paste-template](https://gitee.com/pastecode/paste-template)

**PasteForm操作文档**：[https://soft.pastecode.cn/doc/](https://soft.pastecode.cn/doc/)

apeart / paste-apeart master