---
title: "identifyUser"
description: "核心构建块——从 Better Auth 会话中提取安全的用户字段、屏蔽电子邮件，并捕获插件数据（组织、角色、2FA）。"
canonical_url: "https://evlog.zhcndoc.com/use-cases/better-auth/identify-user"
---
# identifyUser

> 核心构建块——从 Better Auth 会话中提取安全的用户字段、屏蔽电子邮件，并捕获插件数据（组织、角色、2FA）。

`identifyUser` 是核心构建块。传入一个 `RequestLogger` 和一个 Better Auth 会话，提取安全字段，并调用 `log.set()`。如果识别到了用户则返回 `true`，否则返回 `false`。

```typescript [server/api/checkout.post.ts]
import { identifyUser } from 'evlog/better-auth'

const session = await auth.api.getSession({ headers: event.headers })
if (session) {
  const identified = identifyUser(log, session)
  if (identified) {
    log.set({ subscription: 'premium' })
  }
}
```

<tip>

**默认安全。** 只提取列入白名单的字段，密码、令牌和机密信息绝不会写入日志记录器。

</tip>

## 选项

<table>
<thead>
  <tr>
    <th>
      选项
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认值
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        maskEmail
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      将电子邮件屏蔽为 <code>
        h***@example.com
      </code>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      包含会话元数据（<code>
        session.id
      </code>
      
      、<code>
        session.expiresAt
      </code>
      
      、<code>
        session.ipAddress
      </code>
      
      、<code>
        session.userAgent
      </code>
      
      ）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fields
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      <code>
        ['id', 'name', 'email', 'image', 'emailVerified', 'createdAt']
      </code>
    </td>
    
    <td>
      要提取的用户字段。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        extend
      </code>
    </td>
    
    <td>
      <code>
        (session) => Record<string, unknown>
      </code>
    </td>
    
    <td>
      <code>
        undefined
      </code>
    </td>
    
    <td>
      从 Better Auth 插件（组织、角色等）添加自定义字段。
    </td>
  </tr>
</tbody>
</table>

```typescript [services/checkout.ts]
identifyUser(log, session, {
  maskEmail: true,
  fields: ['id', 'name'],
  session: false,
})
```

## 屏蔽电子邮件

电子邮件属于 PII。在审计/日志轨迹可能会被支持人员或第三方查看的环境中，请将其屏蔽：

```typescript
identifyUser(log, session, { maskEmail: true })
```

`maskEmail` 帮助函数也可单独导出：

```typescript
import { maskEmail } from 'evlog/better-auth'

maskEmail('hugo@example.com') // 'h***@example.com'
```

## 捕获插件字段

Better Auth 附带插件（组织、2FA、角色、管理员），它们会向会话中添加字段。使用 `extend` 将它们展示到宽事件中：

```typescript [server/middleware/auth-identify.ts]
import { createAuthMiddleware } from 'evlog/better-auth'

const identify = createAuthMiddleware(auth, {
  extend: (session) => ({
    organization: session.user.activeOrganization,
    role: session.user.role,
  }),
})
```

包含插件字段的宽事件：

```json [Wide Event]
{
  "userId": "QBX9tPjJQExWawAbNll75",
  "user": { "id": "QBX9tPjJQExWawAbNll75", "name": "Hugo Richard" },
  "organization": { "id": "org_42", "name": "Acme" },
  "role": "admin"
}
```

<tip>

请确保 `extend` 是确定性的，因为它会在每个请求中运行。避免在其中执行繁重的计算或额外的数据库调用；应查询 Better Auth 已经加载到会话中的数据。

</tip>

## 进入事件的字段

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      来源
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        userId
      </code>
    </td>
    
    <td>
      <code>
        session.user.id
      </code>
    </td>
    
    <td>
      顶层用户 ID（PostHog 适配器将其用作 <code>
        distinct_id
      </code>
      
      ）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        user.id
      </code>
    </td>
    
    <td>
      <code>
        session.user.id
      </code>
    </td>
    
    <td>
      用户 ID。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        user.name
      </code>
    </td>
    
    <td>
      <code>
        session.user.name
      </code>
    </td>
    
    <td>
      显示名称。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        user.email
      </code>
    </td>
    
    <td>
      <code>
        session.user.email
      </code>
    </td>
    
    <td>
      电子邮件（可通过 <code>
        maskEmail: true
      </code>
      
       屏蔽）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        user.image
      </code>
    </td>
    
    <td>
      <code>
        session.user.image
      </code>
    </td>
    
    <td>
      头像 URL。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        user.emailVerified
      </code>
    </td>
    
    <td>
      <code>
        session.user.emailVerified
      </code>
    </td>
    
    <td>
      电子邮件验证状态。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        user.createdAt
      </code>
    </td>
    
    <td>
      <code>
        session.user.createdAt
      </code>
    </td>
    
    <td>
      账户创建日期（ISO 字符串）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session.id
      </code>
    </td>
    
    <td>
      <code>
        session.session.id
      </code>
    </td>
    
    <td>
      会话 ID。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session.expiresAt
      </code>
    </td>
    
    <td>
      <code>
        session.session.expiresAt
      </code>
    </td>
    
    <td>
      会话过期时间（ISO 字符串）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session.ipAddress
      </code>
    </td>
    
    <td>
      <code>
        session.session.ipAddress
      </code>
    </td>
    
    <td>
      来自会话的客户端 IP。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session.userAgent
      </code>
    </td>
    
    <td>
      <code>
        session.session.userAgent
      </code>
    </td>
    
    <td>
      来自会话的用户代理字符串。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session.createdAt
      </code>
    </td>
    
    <td>
      <code>
        session.session.createdAt
      </code>
    </td>
    
    <td>
      会话创建日期（ISO 字符串）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auth.resolvedIn
      </code>
    </td>
    
    <td>
      已测量
    </td>
    
    <td>
      会话解析耗时，单位为 ms。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        auth.identified
      </code>
    </td>
    
    <td>
      已计算
    </td>
    
    <td>
      请求是否已被识别。
    </td>
  </tr>
</tbody>
</table>

---

- [概览](https://evlog.zhcndoc.com/use-cases/better-auth/overview)
- [中间件](https://evlog.zhcndoc.com/use-cases/better-auth/middleware)


## Sitemap

See the full [sitemap](https://evlog.zhcndoc.com/sitemap.md) for all pages.