应用接口

当你创建一个新的 Better Auth 实例时，它会为你提供一个 api 对象。该对象公开了你 Better Auth 实例中存在的所有端点，你可以使用它与 Better Auth 服务器进行交互。

【When you create a new Better Auth instance, it provides you with an api object. This object exposes every endpoint that exists in your Better Auth instance. And you can use this to interact with Better Auth server side.】

无论是来自插件还是核心，添加到 Better Auth 的任何端点都可以通过 api 对象访问。

【Any endpoint added to Better Auth, whether from plugins or the core, will be accessible through the api object.】

在服务器上调用 API 端点

【Calling API Endpoints on the Server】

要调用服务器上的 API 端点，请导入你的 auth 实例，并使用 api 对象调用该端点。

【To call an API endpoint on the server, import your auth instance and call the endpoint using the api object.】

import { betterAuth } from "better-auth";
import { headers } from "next/headers";

export const auth = betterAuth({
    //...
})

// calling get session on the server
await auth.api.getSession({
    headers: await headers() // some endpoints might require headers
})

主体、标题、查询

【Body, Headers, Query】

与客户端不同，服务器需要将值作为一个对象传递，其中 body 对应请求体，headers 对应请求头，query 对应查询参数。

【Unlike the client, the server needs the values to be passed as an object with the key body for the body, headers for the headers, and query for query parameters.】

await auth.api.getSession({
    headers: await headers()
})

await auth.api.signInEmail({
    body: {
        email: "john@doe.com",
        password: "password"
    },
    headers: await headers() // optional but would be useful to get the user IP, user agent, etc.
})

await auth.api.verifyEmail({
    query: {
        token: "my_token"
    }
})

获取 headers 和 Response 对象

【Getting headers and Response Object】

当你在服务器上调用一个 API 端点时，它会直接返回一个标准的 JavaScript 对象或数组，因为这只是一次普通的函数调用。

【When you invoke an API endpoint on the server, it will return a standard JavaScript object or array directly as it's just a regular function call.】

但有时你可能想获取 headers 或 Response 对象。例如，如果你需要获取 cookies 或 headers。

【But there are times when you might want to get the headers or the Response object instead. For example, if you need to get the cookies or the headers.】

获取 headers

【Getting headers】

要获取 headers，你可以向端点传递 returnHeaders 选项。

【To get the headers, you can pass the returnHeaders option to the endpoint.】

const { headers, response } = await auth.api.signUpEmail({
	returnHeaders: true,
	body: {
		email: "john@doe.com",
		password: "password",
		name: "John Doe",
	},
});

headers 将是一个 Headers 对象，你可以用它来获取 cookies 或者 headers。

【The headers will be a Headers object, which you can use to get the cookies or the headers.】

const cookies = headers.get("set-cookie");
const headers = headers.get("x-custom-header");

获取 Response 对象

【Getting Response Object】

要获取 Response 对象，你可以将 asResponse 选项传递给端点。

【To get the Response object, you can pass the asResponse option to the endpoint.】

const response = await auth.api.signInEmail({
    body: {
        email: "",
        password: ""
    },
    asResponse: true
})

错误处理

【Error Handling】

当你调用服务器上的 API 端点时，如果请求失败，它会抛出一个错误。你可以捕获该错误并按自己的方式处理。这个错误实例是 APIError 的一个实例。

【When you call an API endpoint on the server, it will throw an error if the request fails. You can catch the error and handle it as you see fit. The error instance is an instance of APIError.】

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

try {
    await auth.api.signInEmail({
        body: {
            email: "",
            password: ""
        }
    })
} catch (error) {
    if (error instanceof APIError) {
        console.log(error.message, error.status)
    }
}