当前位置：首页 > news >正文

PetaPoco映射器自定义指南：从标准映射到约定映射

news 2026/4/29 12:13:17

PetaPoco映射器自定义指南：从标准映射到约定映射

【免费下载链接】PetaPocoOfficial PetaPoco, A tiny ORM-ish thing for your POCO's项目地址: https://gitcode.com/gh_mirrors/pet/PetaPoco

PetaPoco作为一款轻量级ORM工具，其核心功能在于将数据库表与POCO类（简单老式CLR对象）之间建立灵活的映射关系。本文将详细介绍如何通过PetaPoco的映射器系统实现从标准映射到高级约定映射的全流程，帮助开发者快速掌握自定义映射规则的实用技巧。

PetaPoco映射器基础：理解IMapper接口

PetaPoco的映射系统基于IMapper接口构建，该接口定义了POCO类与数据库结构之间映射的核心契约。在PetaPoco的源代码中，我们可以在PetaPoco/Core/IMapper.cs找到这个关键接口的定义，它包含了获取表信息、列信息以及数据转换的基本方法。

默认情况下，PetaPoco使用ConventionMapper作为其标准映射器实现。从PetaPoco/Database.cs的初始化代码可以看到：_defaultMapper = mapper ?? new ConventionMapper();，这意味着如果没有指定自定义映射器，系统会自动使用约定映射器。

标准映射器：ConventionMapper的默认行为

ConventionMapper作为PetaPoco的默认映射器，提供了一套开箱即用的映射规则。通过分析PetaPoco/Core/ConventionMapper.cs的源代码，我们可以发现其核心功能包括：

表名与列名映射规则

默认情况下，ConventionMapper采用直接映射策略：

表名与类名保持一致（InflectTableName = (inflect, tn) => tn）
列名与属性名保持一致（InflectColumnName = (inflect, cn) => cn）

这种零配置的映射方式适合大多数简单场景，让开发者能够快速上手而无需编写额外的映射代码。

主键识别逻辑

ConventionMapper通过以下逻辑识别主键：

查找带有[PrimaryKey]特性的属性
如果未找到，则自动识别名为"Id"的属性作为主键
对于数值类型（int、long等）自动启用自增特性（IsPrimaryKeyAutoIncrement方法）

自定义映射规则：灵活配置ConventionMapper

ConventionMapper的强大之处在于其高度可配置性。通过修改其属性委托，我们可以轻松实现自定义映射规则，而无需创建全新的IMapper实现。

自定义表名映射

以下代码展示如何将所有表名添加"TBL_"前缀并转为复数形式：

var mapper = new ConventionMapper(); mapper.InflectTableName = (inflector, tableName) => $"TBL_{inflector.Pluralize(tableName)}";

这段代码利用了PetaPoco内置的Inflector类（位于PetaPoco/Core/Inflection/Inflector.cs），通过Pluralize方法实现表名的复数转换。

自定义列名映射

要将属性名的驼峰式命名转换为数据库的下划线命名：

mapper.InflectColumnName = (inflector, columnName) => inflector.Underscore(columnName);

这将自动把"UserName"这样的属性名转换为"user_name"列名，符合数据库命名规范。

自定义主键规则

如果你的项目中主键命名统一为"PK_表名"，可以这样配置：

mapper.MapPrimaryKey = (tableInfo, pocoType) => { tableInfo.PrimaryKey = $"PK_{tableInfo.TableName}"; tableInfo.AutoIncrement = true; return true; };

数据类型转换

ConventionMapper还支持自定义数据转换逻辑。例如，将数据库的字符串类型转换为枚举类型：

mapper.FromDbConverter = (property, sourceType) => { if (property.PropertyType.IsEnum) { return value => Enum.Parse(property.PropertyType, (string)value); } return null; };

注册自定义映射器

配置好自定义映射器后，需要将其注册到PetaPoco中。有以下几种注册方式：

数据库实例级别注册

var db = new Database(connectionString, new CustomConventionMapper());

全局配置注册

DatabaseConfiguration.Configure() .UsingDefaultMapper<CustomConventionMapper>();

特定实体注册

通过Mappers类（位于PetaPoco/Core/Mappers.cs）可以为特定实体类型注册专用映射器：

Mappers.Register(typeof(Product), new ProductMapper());

高级场景：创建自定义IMapper实现

对于更复杂的映射需求，可以通过实现IMapper接口创建完全自定义的映射器。以下是一个简单示例：

public class CustomMapper : IMapper { public TableInfo GetTableInfo(Type pocoType) { // 自定义表信息逻辑 } public ColumnInfo GetColumnInfo(PropertyInfo pocoProperty) { // 自定义列信息逻辑 } // 实现其他接口方法... }

自定义映射器适合处理特殊场景，如：