首页
/ 使用Payload Better Auth创建你的第一个插件:生日验证功能开发指南

使用Payload Better Auth创建你的第一个插件:生日验证功能开发指南

2025-06-19 17:23:11作者:董灵辛Dennis

Payload Better Auth是一个强大的身份验证解决方案,它允许开发者通过插件机制扩展核心功能。本文将带你从零开始开发一个生日验证插件,通过这个实战案例,你将掌握Payload Better Auth插件开发的核心概念和流程。

前置条件

在开始之前,请确保你已经完成了Payload Better Auth的基础配置工作。本教程假设你已经搭建好了基本的开发环境,并准备好创建你的第一个插件。

第一步:规划插件功能

任何插件开发的第一步都是明确功能需求。在本案例中,我们将开发一个生日插件,主要功能包括:

  1. 记录用户的出生日期
  2. 验证用户年龄是否超过5岁
  3. 提供前后端一致的验证逻辑

第二步:创建服务器端插件

Payload Better Auth的插件采用前后端分离架构,由服务器插件和客户端插件组成。服务器插件负责核心业务逻辑和数据处理,是插件系统的基石。

基础结构搭建

首先创建一个名为birthday-plugin的文件夹,并在其中创建index.ts文件:

birthday-plugin/
└── index.ts

index.ts中,我们导出一个函数来定义我们的服务器插件:

import { createAuthClient } from "better-auth/client";
import type { BetterAuthPlugin } from "better-auth";

export const birthdayPlugin = () =>
  ({
    id: "birthdayPlugin",
  } satisfies BetterAuthPlugin);

虽然这只是一个空壳,但你已经成功创建了第一个插件的基础结构!

定义数据模型

为了存储用户的生日信息,我们需要在用户模型上扩展字段。通过定义schema,Payload Better Auth的CLI工具可以自动生成数据库迁移脚本。

export const birthdayPlugin = () =>
  ({
    id: "birthdayPlugin",
    schema: {
      user: {
        fields: {
          birthday: {
            type: "date",       // 字段类型,支持string/number/boolean/date
            required: true,     // 是否必填,默认为false
            unique: false,      // 是否唯一,默认为false
            reference: null     // 关联字段,默认为null
          },
        },
      },
    },
  } satisfies BetterAuthPlugin);

实现业务逻辑

现在,我们来实现核心功能:验证用户年龄是否超过5岁。这里我们使用**钩子(Hooks)**机制,在特定操作前后执行自定义逻辑。

import { APIError } from "better-auth/api";
import { createAuthMiddleware } from "better-auth/plugins";

export const birthdayPlugin = () => ({
    // ...之前的配置
    
    hooks: {
      before: [
        {
          matcher: (context) => context.path.startsWith("/sign-up/email"),
          handler: createAuthMiddleware(async (ctx) => {
            const { birthday } = ctx.body;
            
            // 类型验证
            if(!birthday instanceof Date) {
              throw new APIError("BAD_REQUEST", { 
                message: "生日必须是有效的日期格式" 
              });
            }

            // 年龄验证
            const today = new Date();
            const fiveYearsAgo = new Date(today.setFullYear(today.getFullYear() - 5));

            if(birthday >= fiveYearsAgo) {
              throw new APIError("BAD_REQUEST", { 
                message: "用户必须年满5岁以上" 
              });
            }

            return { context: ctx };
          }),
        },
      ],
    },
} satisfies BetterAuthPlugin)

这段代码实现了:

  1. 拦截所有注册请求
  2. 验证生日字段是否为有效日期
  3. 计算用户年龄是否超过5岁
  4. 根据验证结果返回相应错误或继续流程

第三步:创建客户端插件

客户端插件主要负责提供类型安全和便捷的前端API。对于生日插件来说,客户端逻辑相对简单。

创建client.ts文件:

birthday-plugin/
├── index.ts
└── client.ts

添加以下内容:

import { BetterAuthClientPlugin } from "better-auth";
import type { birthdayPlugin } from "./index";

type BirthdayPlugin = typeof birthdayPlugin;

export const birthdayClientPlugin = () => {
  return {
    id: "birthdayPlugin",
    $InferServerPlugin: {} as ReturnType<BirthdayPlugin>,
  } satisfies BetterAuthClientPlugin;
};

这个客户端插件主要作用是:

  1. 保持与服务器插件一致的ID
  2. 自动推断服务器插件定义的类型
  3. 为前端提供类型安全的API

第四步:集成插件

完成插件开发后,需要将其集成到你的应用中。

服务器端集成

import { betterAuth } from "better-auth";
import { birthdayPlugin } from "./birthday-plugin";
 
export const auth = betterAuth({
    plugins: [
      birthdayPlugin(),
    ]
});

客户端集成

import { createAuthClient } from "better-auth/client";
import { birthdayClientPlugin } from "./birthday-plugin/client";
 
const authClient = createAuthClient({
    plugins: [
      birthdayClientPlugin()
    ]
});

数据库迁移

最后,别忘了更新数据库模型。你可以手动修改用户表,或使用CLI工具自动生成迁移:

npx @better-auth/cli@latest generate

总结与扩展

通过本教程,你已经成功开发了一个完整的Payload Better Auth插件。这个生日验证插件虽然简单,但涵盖了插件开发的所有关键环节:

  1. 服务器插件开发
  2. 数据模型定义
  3. 业务逻辑实现
  4. 客户端插件创建
  5. 系统集成

如果你想进一步扩展这个插件,可以考虑:

  1. 添加更多验证规则(如最大年龄限制)
  2. 实现生日提醒功能
  3. 添加基于年龄的分组功能
  4. 开发管理界面查看用户年龄分布

Payload Better Auth的插件系统非常灵活,掌握这些基础知识后,你可以开发出各种强大的身份验证扩展功能。

登录后查看全文
热门项目推荐

项目优选

收起
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
143
1.92 K
kernelkernel
deepin linux kernel
C
22
6
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台,包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分,采用java语言实现,可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
8
0
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
C++
192
274
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot,Spring Security,JWT,Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
929
553
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件,通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求,让密码技术应用更简单,同时探索后量子等先进算法创新实践,构建密码前沿技术底座!
C
422
392
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
145
189
金融AI编程实战金融AI编程实战
为非计算机科班出身 (例如财经类高校金融学院) 同学量身定制,新手友好,让学生以亲身实践开源开发的方式,学会使用计算机自动化自己的科研/创新工作。案例以量化投资为主线,涉及 Bash、Python、SQL、BI、AI 等全技术栈,培养面向未来的数智化人才 (如数据工程师、数据分析师、数据科学家、数据决策者、量化投资人)。
Jupyter Notebook
75
65
Cangjie-ExamplesCangjie-Examples
本仓将收集和展示高质量的仓颉示例代码,欢迎大家投稿,让全世界看到您的妙趣设计,也让更多人通过您的编码理解和喜爱仓颉语言。
Cangjie
344
1.3 K
easy-eseasy-es
Elasticsearch 国内Top1 elasticsearch搜索引擎框架es ORM框架,索引全自动智能托管,如丝般顺滑,与Mybatis-plus一致的API,屏蔽语言差异,开发者只需要会MySQL语法即可完成对Es的相关操作,零额外学习成本.底层采用RestHighLevelClient,兼具低码,易用,易拓展等特性,支持es独有的高亮,权重,分词,Geo,嵌套,父子类型等功能...
Java
36
8