通知最终用户

20.1.2.1 通过返回 True/False 做验证#

类型为 PL/SQL Expression 的验证会把表达式结果作为通过与否的判断：表达式返回 true 时数据有效；返回 false 时显示验证的 Error Message。

例如，验证“两个字段不能都以 4 开头”可以写成下面的表达式。它的含义是：不是两个页面项的首字符都等于 4。

not (
  substr(:P3_MULTIPLE_OF_TEN,1,1) = '4'
  and substr(:P3_ODD_MULTIPLE_OF_FIVE,1,1) = '4'
)

等价地，也可以表达为“至少有一个字段首字符不是 4”。

substr(:P3_MULTIPLE_OF_TEN,1,1) != '4'
or substr(:P3_ODD_MULTIPLE_OF_FIVE,1,1) != '4'

为了支持翻译，可以定义名为 CANNOT_BOTH_START 的文本消息，并使用 first_digit 占位符。

Cannot both start with a %first_digit

验证的错误消息属性可以这样引用它：

&{CANNOT_BOTH_START first_digit="4"}.

官方来源：Validating By Returning True/False Result

20.1.2.2 通过返回错误文本做验证#

类型为 Function Body (returning Error Text) 的验证使用返回值表达结果：返回 null 表示通过；返回其他文本表示失败，且该文本就是要显示的错误消息。

下面示例检查两个数字字段是否至少有一个大于 100。如果都小于 100，则通过 APEX_LANG.GET_MESSAGE 返回可翻译错误消息。

return case
  when :P3_MULTIPLE_OF_TEN < 100
   and :P3_ODD_MULTIPLE_OF_FIVE < 100 then
    apex_lang.get_message(
      'AT_LEAST_N_ABOVE_M',
      apex_t_varchar2(
        'mincount','1',
        'limit','100'))
end;

这里的 CASE 没有 ELSE 分支，因此条件不满足时自然返回 null，验证通过。

官方来源：Validating By Returning Error Text

20.1.5.1 在 PL/SQL 中添加错误消息#

APEX_ERROR.ADD_ERROR 用于在服务器端处理中向用户报告错误。它会停止后续处理，放弃未提交的数据变更，并在通知区域显示错误。

这种方式特别适合放在保存数据之后、APEX 最终提交之前的页面进程中，用来检查跨行、聚合或业务级规则。

官方来源：Adding an Error Message in PL/SQL

20.1.5.1.2 用 SQL 聚合实现约束

假设业务规则要求每个部门的月度总薪酬不能超过 12000。下面的查询用 SUM、GROUP BY 和 HAVING 找出超限部门。COALESCE 把空工资或佣金按 0 处理。

-- Return any departments over monthly compensation limit
select deptno,
       sum(coalesce(sal,0) + coalesce(comm,0)) as total_comp
from emp
group by deptno
having sum(coalesce(sal,0) + coalesce(comm,0)) > 12000

过程 CHECK_DEPARTMENTS_OVERBUDGET 遍历这些部门，把部门号和总薪酬加入字符串列表。如果列表不为空，就调用 APEX_ERROR.ADD_ERROR，显示通过 APEX_LANG.GET_MESSAGE 取得的可翻译消息。

-- In package messages_app
procedure check_departments_overbudget is
  l_overbudget apex_t_varchar2;
begin
  for j in (
    select deptno,
           sum(coalesce(sal,0) + coalesce(comm,0)) as total_comp
    from emp
    group by deptno
    having sum(coalesce(sal,0) + coalesce(comm,0)) > 12000
    order by deptno) loop
    apex_string.push(
      l_overbudget,
      apex_string.format('%s (%s)',j.deptno,j.total_comp));
  end loop;

  if l_overbudget is not null then
    apex_error.add_error (
      p_message => apex_lang.get_message(
        'OVERBUDGET_DEPARTMENTS',
        apex_t_varchar2(
          'department_list',apex_string.join(l_overbudget,', '),
          'amount' ,'12000')),
      p_display_location => apex_error.c_on_error_page);
  end if;
end check_departments_overbudget;

这类检查不能放在普通验证中，因为验证运行在 Processing 阶段之前，看不到保存进程即将提交的数据。把它放在保存进程之后的页面进程中，既能看到待提交变更，又能通过错误否决事务。

官方来源：Applying Aggregate Constraints with SQL

20.1.5.2 使用 JavaScript 显示消息#

客户端逻辑可以调用 apex.message.showPageSuccess 显示成功消息，调用 apex.message.showErrors 显示一个或多个页面级或字段级错误，并用 apex.message.clearErrors 清除所有错误或某个页面项的错误。

下面示例补充一个 CHECK_DEPTNO 函数，用于即时验证部门编号。

-- In package messages_app
function check_deptno(
  p_deptno in number)
  return varchar2
is
begin
  for j in (select null from dept where deptno = p_deptno) loop
    return null; -- valid
  end loop;
  return apex_lang.get_message('INVALID_DEPTNO'); -- invalid
end;

目标是在用户提交页面前，同时对 P5_EMPNO 与 P5_DEPTNO 做服务器端检查，并把错误显示在对应字段下方。

在 P5_EMPNO 的 Change 事件动态操作中，先执行 JavaScript 清除该字段已有错误。

apex.message.clearErrors('P5_EMPNO');

然后 Execute Server-side Code 动作调用服务器端函数，把返回的错误消息写入隐藏页面项 P5_INVALID_MESSAGE。

:P5_INVALID_MESSAGE := messages_app.check_empno(:P5_EMPNO);

最后用 showErrors 把服务器返回的消息显示在 P5_EMPNO 字段附近。该动作应配置客户端条件，仅在 P5_INVALID_MESSAGE 不为空时执行。

apex.message.showErrors(
  [
    {
      type: "error",
      location: [ "inline" ],
      pageItem: "P5_EMPNO",
      message: $v('P5_INVALID_MESSAGE')
    }
  ] );

如果错误消息文本包含 HTML 标记，可向 showErrors 传入额外属性 unsafe: false，避免尖括号等保留字符被转义。

验证 P5_DEPTNO 时复用同一模式：提交部门编号，调用 CHECK_DEPTNO，把错误放到同一个隐藏项，再把消息显示在 P5_DEPTNO 字段上。

官方来源：Displaying Messages with JavaScript

20.1.6.1 观察默认错误行为#

为了理解自定义错误处理的价值，可以先看默认行为。假设在 EMP 表上增加约束，要求佣金不能超过工资的两倍。

alter table emp add constraint comm_less_than_twice_sal
check (comm < 2 * sal);

默认情况下，违反该约束时，用户会看到包含约束名的数据库错误，例如 ORA-02290: check constraint (SCHEMA.COMM_LESS_THAN_TWICE_SAL) violated。这对开发者有用，但对普通用户不够友好。

APEX 引擎内部错误也类似。默认消息可能说明技术原因，并提示联系应用管理员，例如表单区域没有定义主键项。

官方来源：Studying Default Error Message Behavior

20.1.6.2 指定错误处理函数#

APEX 引擎会在报告服务器端错误前调用错误处理函数。函数名称可以自定义，但签名必须接收 apex_error.t_error，并返回 apex_error.t_error_result。

-- In package messages_app
function apex_error_handling (
  p_error in apex_error.t_error )
  return apex_error.t_error_result;

实际项目中通常把函数放在应用包中，例如 MESSAGES_APP。然后在页面属性的 Error Handling Function 中填写函数名。

官方来源：Specifying an Error Handling Function

20.1.6.3 阅读错误处理函数代码#

典型错误处理函数会先调用 apex_error.init_error_result 初始化返回结果。对于少见的内部错误，它记录日志，并把用户看到的消息替换成通用文本消息。对于数据库约束错误，它提取约束名，再尝试查找对应的可翻译文本消息。

-- In package messages_app
function apex_error_handling (
  p_error in apex_error.t_error )
  return apex_error.t_error_result
is
  l_result          apex_error.t_error_result;
  l_constraint_name varchar2(255);
  l_error_message   varchar2(255);
begin
  l_result := apex_error.init_error_result(p_error);

  if p_error.is_internal_error then
    if not p_error.is_common_runtime_error then
      add_error_log(p_error);
      l_result.message := apex_lang.get_message('UNEXPECTED_INTERNAL_ERROR');
      l_result.additional_info := null;
    end if;
  else
    l_result.display_location := apex_error.c_inline_in_notification;

    if p_error.ora_sqlcode in (-1, -2091, -2290, -2291, -2292) then
      l_constraint_name := apex_error.extract_constraint_name(
        p_error => p_error );
      begin
        l_error_message :=
          apex_lang.get_message('CONSTRAINT_' || l_constraint_name);

        if l_error_message != 'CONSTRAINT_' || l_constraint_name then
          l_result.message := l_error_message;
        end if;
      exception
        when no_data_found then
          null;
      end;
    end if;

    if p_error.ora_sqlcode is not null
       and l_result.message = p_error.message then
      l_result.message := apex_error.get_first_ora_error_text(
        p_error => p_error );
    end if;
  end if;

  return l_result;
end apex_error_handling;

这里的约束消息约定是：如果约束名为 XXX，则查找文本消息 CONSTRAINT_XXX。如果找到了真正的文本，就把它作为用户消息；如果没有，就退回到简化后的 ORA 错误文本。

官方来源：Examining Error Handling Function Code

20.1.6.4 记录错误信息用于排查#

辅助过程 ADD_ERROR_LOG 接收 APEX 传入的 T_ERROR 记录，把错误上下文写入自定义日志表。日志表可以保存应用、页面、用户、浏览器、IP、页面项、区域、列、行号、APEX 错误码、ORA 错误码、调用栈等信息。

create table messages_app_errors (
  id number generated by default on null as identity not null,
  err_time timestamp(6) default systimestamp,
  app_id number,
  app_page_id number,
  app_user varchar2(512),
  user_agent varchar2(4000),
  ip_address varchar2(512),
  ip_address2 varchar2(512),
  message varchar2(4000),
  page_item_name varchar2(255),
  region_id number,
  column_alias varchar2(255),
  row_num number,
  apex_error_code varchar2(255),
  ora_sqlcode number,
  ora_sqlerrm varchar2(4000),
  error_backtrace varchar2(4000),
  procedure_name varchar2(1000),
  error_text varchar2(4000),
  constraint message_app_errors_id_pk primary key (id)
);

日志过程使用自治事务（pragma autonomous_transaction），并在插入日志后显式 commit。这样即使 APEX 因错误回滚业务数据，排查日志也能保留下来。

-- In package messages_app
procedure add_error_log (
  p_error in apex_error.t_error,
  p_procedure_name in varchar2 default null,
  p_error_text in varchar2 default null)
is
  pragma autonomous_transaction;
begin
  delete from messages_app_errors
  where err_time <= current_timestamp - 21;

  insert into messages_app_errors (
    app_id, app_page_id, app_user, user_agent,
    ip_address, ip_address2, message, page_item_name,
    region_id, column_alias, row_num, apex_error_code,
    ora_sqlcode, ora_sqlerrm, error_backtrace,
    procedure_name, error_text)
  select v('APP_ID'),
         v('APP_PAGE_ID'),
         v('APP_USER'),
         owa_util.get_cgi_env('HTTP_USER_AGENT'),
         owa_util.get_cgi_env('REMOTE_ADDR'),
         sys_context('USERENV', 'IP_ADDRESS'),
         substr(p_error.message,0,4000),
         p_error.page_item_name,
         p_error.region_id,
         p_error.column_alias,
         p_error.row_num,
         p_error.apex_error_code,
         p_error.ora_sqlcode,
         substr(p_error.ora_sqlerrm,0,4000),
         substr(p_error.error_backtrace,0,4000),
         p_procedure_name,
         p_error_text
  from dual;

  commit;
end add_error_log;

完整字段可参考 APEX_ERROR 包文档中 T_ERROR 记录的说明。

官方来源：Logging Error Info for Troubleshooting

20.1.6.5 体验自定义错误处理#

配置错误处理函数后，可以通过约束违反、数据库异常和内部错误来验证效果。下面的触发器故意制造两种数据库错误：当 COMM 为 1234 时触发除零错误；当 COMM 为 1235 时抛出 RAISE_APPLICATION_ERROR。

create or replace trigger emp_conditional_error_test
before insert or update on emp
for each row
begin
  if :new.comm = 1234 then
    if :new.comm / 0 > 1 then
      null;
    end if;
  elsif :new.comm = 1235 then
    raise_application_error(-20020,'Some error from the database');
  end if;
end;

当用户输入的佣金超过工资两倍时，错误处理函数可以把约束错误转换为文本消息 CONSTRAINT_COMM_LESS_THAN_TWICE_SAL 对应的友好文案。

当用户输入 1235 时，页面显示的是简化后的数据库异常文本，而不是完整技术堆栈。

当用户输入 1234 造成除零错误时，用户也只看到简化后的错误，例如 divisor is equal to zero。

对于少见的内部 APEX 错误，错误处理函数可以向用户显示通用消息，同时把详细信息记录到日志表。例如紧急修复时误关表单主键项的 Primary Key 开关，生产用户可能只看到“发生了意外的内部应用错误”。

管理员可以查看只对管理员开放的日志页面，定位错误发生在哪个应用和页面。

进入详情后，可以看到错误处理函数记录的更多上下文，从而快速修复并重新发布应用。

官方来源：Experiencing Custom Error Handling