使用 Clerk 与 Express 实现 API 请求身份验证的完整指南

在现代应用程序中，API 是系统间通信和数据共享的核心。然而，随着 API 功能的不断增强，确保其安全性变得至关重要。未经授权的访问可能导致数据泄露、安全漏洞，甚至危及整个应用的完整性。本文将详细介绍如何使用 Clerk 与 Express，通过 ClerkExpressWithAuth() 和 ClerkExpressRequireAuth() 中间件，实现 API 请求身份验证，快速构建安全可靠的后端服务。

一. 为什么 API 请求身份验证至关重要？

API 身份验证对于开发安全的后端系统非常关键，其主要价值体现在：

提升安全性
确保只有授权用户或客户端能够访问 API，防止数据被窃取或非法修改。
保护数据完整性
验证请求来源，有效阻止恶意操作对系统造成破坏。

虽然某些路由（如登录或注册）需要保持开放状态，但默认情况下建议对所有 API 路由启用身份验证。使用专业工具（如 Clerk）可显著简化开发流程并提高安全性。

二. Clerk 提供的两种身份验证中间件

Clerk 为 Express 提供了两种中间件：

ClerkExpressWithAuth()
宽松身份验证中间件，未认证请求会返回一个空的 auth 对象。
ClerkExpressRequireAuth()
严格身份验证中间件，未认证请求会直接返回错误（HTTP 401）。

主要区别在于对未认证请求的处理方式。

三. Express 核心概念：回调函数与中间件

1. 回调函数

回调函数是作为参数传递给其他函数，并在稍后被调用的函数。Node.js 广泛使用回调函数处理异步操作，如 HTTP 请求。

2. 中间件

中间件是一个函数，可以访问请求对象 (req)、响应对象 (res) 以及下一个中间件 (next)。中间件可以：

修改请求或响应对象
终止请求-响应循环
调用下一个中间件

在 Express 中，路由处理函数本质上也是中间件，因为它们可以访问 req、res 和 next 对象。

四. 使用 ClerkExpressWithAuth() 实现宽松身份验证

1. 设置后端环境

mkdir backend
cd backend
npm init -y
npm install express dotenv @clerk/clerk-sdk-node

在 .env 文件中添加 Clerk API 密钥：

CLERK_API_KEY=your-clerk-api-key

2. 创建 Express 服务器

import express from "express";
import "dotenv/config";
import { ClerkExpressWithAuth } from "@clerk/clerk-sdk-node";

const app = express();

app.use(ClerkExpressWithAuth());

app.get("/protected-endpoint", (req, res) => {
    res.json({ auth: req.auth });
});

app.listen(3000, () => {
    console.log("Server running on http://localhost:3000");
});

启动服务器：

node app.js

此时，未认证请求将返回空 auth 对象。

五. 创建 React 前端客户端

1. 设置前端环境

npx create-react-app auth-frontend
cd auth-frontend
npm install @clerk/clerk-react isomorphic-fetch es6-promise

在 .env 文件中添加公开 Clerk API 密钥：

REACT_APP_CLERK_PUBLISHABLE_KEY=your-clerk-publishable-key

2. 配置 ClerkProvider

修改 src/App.js：

import React from "react";
import { ClerkProvider, SignedIn, SignedOut, SignIn } from "@clerk/clerk-react";
import Auth from "./auth";

const clerkFrontendApi = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY;

function App() {
    return (
        <ClerkProvider publishableKey={clerkFrontendApi}>
            <SignedIn>
                <Auth />
            </SignedIn>
            <SignedOut>
                <SignIn />
            </SignedOut>
        </ClerkProvider>
    );
}

export default App;

3. 创建 Auth 组件

src/auth.js：

import React, { useEffect } from "react";
import fetch from "isomorphic-fetch";

function Auth() {
    useEffect(() => {
        const fetchProtectedData = async () => {
            const token = await window.Clerk.session.getToken();
            const response = await fetch("http://localhost:3000/protected-endpoint", {
                headers: { Authorization: Bearer ${token} },
            });
            const data = await response.json();
            console.log(data);
        };
        fetchProtectedData();
    }, []);

    return <div>Authenticated!</div>;
}

export default Auth;

此时，React 客户端登录后会向后端发送带身份验证令牌的请求，后端通过 ClerkExpressWithAuth() 验证并返回用户信息。

六. 使用 ClerkExpressRequireAuth() 实现严格身份验证

将中间件替换为：

import { ClerkExpressRequireAuth } from "@clerk/clerk-sdk-node";

app.use(ClerkExpressRequireAuth());

此时，未认证请求将直接返回 401 错误，不会暴露任何 auth 对象信息。

七. 总结

通过本教程，你已经掌握了如何使用 Clerk 与 Express 为 API 添加身份验证：

ClerkExpressWithAuth()：宽松身份验证，返回空 auth 对象
ClerkExpressRequireAuth()：严格身份验证，未认证请求直接报错

下一步，可以探索 Clerk 的其他功能，如 用户管理、会话管理 等，进一步提升应用安全性和用户体验。

原文链接: https://clerk.com/blog/how-to-authenticate-api-requests-with-clerk-express