# ERPNext 语法：白名单方法白名单方法将 Python 函数公开为 REST API 端点。 ## 快速参考 ### 基本白名单方法进口冰沙 @frappe.whitelist() def get_customer_summary(客户): """基本 API 端点 - 仅限经过身份验证的用户。""" 如果不是 frappe.has_permission("Customer", "read"): frappe.throw(_("不允许"), frappe.PermissionError) return frappe.get_doc("客户", customer).as_dict() ### 端点 URL `/api/method/myapp.api.get_customer_summary` ** ** ## 装饰器选项参数|默认 |描述 ---|---|--- `允许来宾` | ‘假’| `True` = 无需登录即可访问 `方法` |全部 | `["GET"]`、`["POST"]` 或组合 `xss_safe` | ‘假’| `True` = 不转义 HTML # 公共端点，仅 POST @frappe.whitelist(allow_guest=True, 方法=["POST"]) def Submit_contact_form(姓名、电子邮件、消息): # 使用访客访问仔细验证输入！如果没有姓名或电子邮件： frappe.throw(_("需要姓名和电子邮件")) 返回{“成功”：True} # 只读端点 @frappe.whitelist(方法=[“GET”]) def get_status(order_id): return frappe.db.get_value("销售订单", order_id, "status") **完整选项** ：参见 [decorator-options.md]() ** ** ## 权限模式 ### 始终检查权限 @frappe.whitelist() def get_data(文档类型, 名称): # 获取数据之前检查如果不是 frappe.has_permission(doctype, "read", name): frappe.throw(_("不允许"), frappe.PermissionError) 返回 frappe.get_doc(doctype, name).as_dict() ### 基于角色的访问 @frappe.whitelist() def admin_function(): frappe.only_for("System Manager") # 如果用户缺少角色则抛出异常返回{“admin_data”：“敏感”} @frappe.whitelist() def multi_role_function(): frappe.only_for(["系统经理", "人力资源经理"]) 返回{“数据”：“值”} **安全模式**：参见[permission-patterns.md]() ** ** ## 错误处理 ### frappe.throw() 用于处理面向用户的错误 @frappe.whitelist() def process_order(order_id, 金额): # 验证错误如果不是 order_id: frappe.throw(_("需要订单 ID"), title=_("缺少数据")) # 权限错误如果不是 frappe.has_permission("销售订单", "写入"): frappe.throw(_("不允许"), frappe.PermissionError) # 业务逻辑错误如果金额 < 0：冰沙.扔( _("金额不能为负数：{0}").format(amount), frappe.ValidationError ） ### 异常类型和 HTTP 代码例外| HTTP 代码 |当 ---|---|--- `frappe.ValidationError` | 417 | 417验证错误 `frappe.PermissionError` | 403 | 403访问被拒绝 `frappe.DoesNotExistError` | 404 | 404未找到 `frappe.DuplicateEntryError` | 409 | 409重复 `frappe.AuthenticationError` | 401 | 401未登录 ### 稳健的错误模式 @frappe.whitelist() defRobust_API（参数）：尝试：结果=过程数据（参数）返回{“成功”：True，“数据”：结果} 除了 frappe.DoesNotExistError： frappe.local.response["http_status_code"] = 404 return {"success": False, "error": "未找到"} 除了frappe.PermissionError： frappe.local.response["http_status_code"] = 403 return {"success": False, "error": "访问被拒绝"} 除了例外： frappe.log_error(frappe.get_traceback(), "API 错误") frappe.local.response["http_status_code"] = 500 return {"success": False, "error": "内部错误"} **完整错误模式**：请参阅 [error-handling.md]() ** ** ## 响应模式 ### 返回值（推荐） @frappe.whitelist() def get_summary(客户): 返回{ “客户”：客户， “总计”：15000 } # 响应: {"message": {"customer": "...", "total": 15000}} ### 自定义 HTTP 状态 @frappe.whitelist() def create_item(数据): 如果没有数据： frappe.local.response["http_status_code"] = 400 返回{“错误”：“需要数据”} # ...创建项目 frappe.local.response["http_status_code"] = 201 返回{“创建”：True} **完整响应模式**：请参阅 [response-patterns.md]() ** ** ## 客户来电 ### frappe.call() - 独立 API // 基于 Promise（推荐）冰沙.call({ 方法：'myapp.api.get_customer_summary'， args: { 客户: 'CUST-00001' } }).then(r => { console.log(r.message); }); // 带加载指示器冰沙.call({ 方法：'myapp.api.process_data'，参数：{数据：myData}，冻结：真实， freeze_message: __('正在处理...') }); ### frm.call() - 控制器方法 frm.call('calculate_taxes', { include_shipping: true }).then(r => { frm.set_value('tax_amount', r.message.tax_amount); }); **完整的客户端模式**：参见 [client-calls.md]() ** ** ## 决策树：哪些选项？谁可以调用 API？ │ ├─► 有人（包括客人）吗？ │ └─► allowed_guest=True + 额外的输入验证 │ └─► 仅限登录用户？ │ └─► 需要特定角色吗？ ├─► 是 → 方法中的 frappe.only_for("RoleName") └─► 否 → frappe.has_permission() 检查哪些 HTTP 方法？ │ ├─► 只读？ │ └─► 方法=["GET"] │ ├─► 只写？ │ └─► 方法=["POST"] │ └─► 两者皆有？ └─►methods=["GET", "POST"] 或默认（全部） ** ** ## 安全检查表对于每个白名单方法： * 存在权限检查（`frappe.has_permission()` 或 `frappe.only_for()`） * 输入验证（类型、范围、格式） * 无SQL注入（参数化查询） * 错误消息中没有敏感数据 * 仅在有明确原因的情况下`allow_guest=True` * `ignore_permissions=True` 仅适用于角色检查 * 尽可能限制 HTTP 方法 ** ** ## 关键规则 ### 1\.永远不要跳过权限检查 # ❌ 错误 - 任何人都可以看到所有数据 @frappe.whitelist() def get_all_salaries(): return frappe.get_all("工资单", fields=["*"]) # ✅ 正确 @frappe.whitelist() def get_salaries(): frappe.only_for("人力资源经理") return frappe.get_all("工资单", fields=["*"]) ### 2\.切勿在 SQL 中使用用户输入 # ❌ 错误 - SQL 注入！ @frappe.whitelist() def 搜索（术语）： return frappe.db.sql(f"SELECT * FROM tabCustomer WHERE name LIKE '%{term}%'") # ✅ 正确 - 参数化 @frappe.whitelist() def 搜索（术语）：返回frappe.db.sql(""" SELECT * FROM tabCustomer WHERE name LIKE %(term)s """, {"term": f"%{term}%"}, as_dict=True) ### 3\.切勿在错误中泄漏敏感数据 # ❌ 错误 - 泄露内部信息除了异常 e： frappe. throw(str(e)) # 可能会泄漏堆栈跟踪！ # ✅ 正确除了例外： frappe.log_error(frappe.get_traceback(), "API 错误") frappe.throw(_("发生错误")) **所有反模式**：参见 [anti-patterns.md]() ** ** ## 版本差异（v14 与 v15）特色 | v14 | v15 ---|---|--- 类型注释验证 | ❌ | ✅ API v2 端点 | ❌ | ✅ `/api/v2/` 速率限制装饰器 | ❌ | ✅ `@rate_limit()` 记录方法端点 |不适用 | `/api/v2/document/{dt}/{name}/method/{m}` ### v15 类型验证 @frappe.whitelist() def get_orders(客户: str, limit: int = 10) -> dict: """v15 根据请求自动验证类型。""" return {"orders": frappe.get_all("销售订单", limit=limit)} ** ** ## 参考文件文件|内容 ---|--- [decorator-options.md]() |所有 @frappe.whitelist() 参数 [parameter-handling.md]() |请求参数及类型转换 [response-patterns.md]() |响应类型和结构 [client-calls.md]() | frappe.call() 和 frm.call() 模式 [permission-patterns.md]() |安全最佳实践 [error-handling.md]() |错误模式和异常类型 [examples.md]() |完整的 API 工作示例 [anti-patterns.md]() |要避免什么

Erpnext 语法白名单

包含技能