FUNC 平台函数 API 认证最佳实践

一、 背景：为什么我们需要函数 API 认证？

1.1 Serverless 架构的崛起

• 从单体到微服务，再到函数：简述应用架构的演进历程。强调函数作为最小的部署单元，使得服务更加原子化、解耦更彻底。
• API 网关的角色：解释 API 网关在 Serverless 架构中的核心地位——它作为所有流量的入口，负责请求路由、日志记录、速率限制，以及至关重要的身份认证。

1.2 传统认证方式的局限

• 单体应用中的认证：在传统单体或微服务应用中，认证逻辑通常由一个统一的“用户中心”或“认证服务”处理，或者通过框架（如 Spring Security, Passport.js）的中间件实现。
• Serverless 下的挑战：当每个函数都是一个独立的执行单元时，如果每个函数都内嵌一套完整的认证逻辑，将导致大量的代码冗余、维护困难，并且难以实现统一的安全策略。

1.3 函数认证的诞生

• 概念定义：函数 API 认证是一种将认证逻辑本身也封装成一个独立函数（我们称之为“认证函数”或“Authorizer Function”）的模式。API 网关在将请求路由到业务函数之前，会先调用这个认证函数来对请求进行验证。
• 核心思想：将“认证”这个横切关注点（Cross-cutting Concern）从业务逻辑中剥离出来，实现了安全逻辑与业务逻辑的彻底解耦。

二、 核心价值：函数认证带来的优势

• 职责单一（Single Responsibility）：业务函数只需专注于核心业务，无需关心认证细节。认证函数也只需专注于安全校验，两者各司其职，代码更清晰、更易于测试和维护。
• 代码复用（Reusability）：一个写好的认证函数可以被成百上千个业务函数共享，无需重复编写认证代码。更新安全策略时，只需修改这一个认证函数即可。
• 性能优势：许多云平台会对认证函数的执行结果进行缓存。对于同一个用户的连续请求，只要其令牌未过期，API 网关可以直接使用缓存的认证结果，无需重复调用认证函数，从而显著降低延迟。

三、 实现方式：构建一个自定义认证函数

本章节将通过一个具体的实例，展示如何从零开始构建一个基于 Token 的自定义认证流程。

前提条件

• 安装 DataFlux Func 平台，请参考：https://func.guance.com/doc/quick-start/
• 注册观测云，请参考：https://auth.guance.com/businessRegister

详细步骤

1、登录 FUNC 平台，在 FUNC 平台内新建一个函数认证脚本AuthFunction，检查请求头中的 x-auth-token 是否为符合认证的 token 。

@DFF.API('AuthFunction')
def my_auth_func():
    # 获取 / 检查 Header 中字段，并返回一个字符串作为错误信息
    try:
        is_valid_header = _DFF_HTTP_REQUEST['headers']['x-auth-token'] == 'my-auth-token'
    except Exception as e:
        return 'Missing `x-auth-token` in header'

    # 认证失败时，可以直接抛出 Exception
    if not (is_valid_header):
        raise Exception('Bad Auth Token')

    # 认证成功时，返回 True
    return True

2、FUNC 平台内新建业务数据脚本。

@DFF.API('BusinessFunction')
def my_main_api():
    # 您的业务代码，例如从数据库获取信息等
    return {"data": "这是受保护的业务数据！"}

3、在 FUNC 平台内中，点击「管理」-「API认证」-「新建」，选择刚刚创建的认证函数。

4、在 FUNC 平台内中，点击「管理」-「函数API」-「新建」，选择刚刚创建的业务函数，且配置中的 API 认证选择上一步创建的认证函数。

5、创建后，FUNC 平台会根据创建的 API，生成调用示例，可以直接复制使用。

使用示例

场景一：调用此 API 查询数据，但是传入了错误的 token ：

curl -H "x-auth-token: error" "http://your-address/api/v1/func-api/verify__BusinessFunction.my_main_api.iCrHwXhi/s"
#调用结果返回：
{
"ok": false, "error": 401.99, "reason": "EAPIAuth", "message": "Func Auth failed", "detail": {
"name": "Func.Runner", "id": "task-ClXiYU7Gxsju", "triggerTime": 1755499568.502, "startTime": 1755499568.503, "endTime": 1755499568.51, "status": "failure", "exceptionType": "UserScriptException", "exception": "In User Script: Exception('Bad Auth Token')", "exceptionFrom": "userScript", "originExceptionType": "Exception", "originException": "Exception('Bad Auth Token')"}, 
    "status": 401, "reqDump": {
"method": "GET", "url": "http://xx.xxx.xxx.xx:xxxx/api/v1/func-api/verify__BusinessFunction.my_main_api.iCrHwXhi/s"}, 
    "traceId": "TRACE-06546AD9-6FA6-406F-953D-E121D3881788", "clientTime": null, "reqTime": "2025-08-18T06:46:08.500Z", "respTime": "2025-08-18T06:46:08.513Z", "reqCost": 13}

场景二：传入正确 token ：

curl -H "x-auth-token: my-auth-token" "http://your-address/api/v1/func-api/verify__BusinessFunction.my_main_api.iCrHwXhi/s"

#调用API结果返回
{
  "data": "这是受保护的业务数据！"
}

四、 总结

FUNC 平台所提供的函数认证机制，不仅仅是一项功能，更是一种先进的架构思想的体现。它将复杂的安全问题抽象化、模块化，并以一种对开发者极其友好的方式呈现出来。这使得我们能够以更低的成本、更高的效率，构建出既灵活又安全的现代化、可扩展的 Serverless 应用。掌握并善用这一利器，无疑是每一位云原生时代开发者走向卓越的必经之路。