循序渐进 · 教学 · 函数（十九）
面向用户的错误（UserFacingError）
函数在 Workshop 或动作里运行时，抛普通异常用户看不懂。用 UserFacingError 可以把一句人话直接显示给用户。
本文来源 · Source
内容整理自 Palantir Foundry 官方文档：
https://www.palantir.com/docs/foundry/functions/user-facing-error/
原始标题：Language-agnostic features > User-facing errors
https://www.palantir.com/docs/foundry/functions/user-facing-error/
原始标题：Language-agnostic features > User-facing errors
★
先记住这几条
① 普通异常对用户是黑盒
用户只会看到无意义的报错，不知道该怎么改。
② UserFacingError 带人话消息
抛这个错误，消息会原样展示给终端用户。
③ 三种语言写法一致
TS v1、TS v2、Python 都是 throw/raise 一个 UserFacingError。
④ 用途：引导用户自助修正
好的错误文案能直接告诉用户「你哪里填错了」。
0
写在前面
当函数在平台的其他地方（比如 Workshop 或动作）运行时，你可能希望抛出一个带有详细说明的错误。做法是抛出 UserFacingError。例如：
import { Function, UserFacingError } from "@foundry/functions-api";
import { Employee } from "@foundry/ontology-api";
export class MyFunctions {
@Function()
public async searchExactlyFiveEmployees(employees: Employee[]): Proimse<string> {
if (employees.length != 5) {
throw new UserFacingError(`请传入正好 5 名员工。实际收到 ${employees.length} 名。`);
}
// 搜索员工
}
}import { Osdk } from "@osdk/client";
import { Employee } from "@ontology/sdk";
import { UserFacingError } from "@osdk/functions";
export default async function searchExactlyFiveEmployees(employees: Array<Osdk.Instance<Employee>>): Promise<string> {
if (employees.length != 5) {
throw new UserFacingError(`请传入正好 5 名员工。实际收到 ${employees.length} 名。`);
}
// 搜索员工
}from functions.api import function, UserFacingError
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Aircraft
@function()
def search_exactly_five_employees(
employees: list[Aircraft]
) -> str:
if not len(aircraft) == 5:
raise UserFacingError(f"请传入正好 5 名员工。实际收到 ${len(aircraft)} 名。")
# 搜索员工如果把它作为函数动作在一个 Workshop 应用里运行，并且传入的员工数量不对，用户会看到下面这个错误：
当一个用在函数导出里的函数抛出 UserFacingError 时，导出失败的提示条会显示这条错误信息。
一句详细的面向用户错误信息，能帮用户自己定位并解决问题。
延伸阅读 · 相关页面
按主题横向跳转，不必顺着目录一篇篇读。