pythia-package

设计包、过程、函数和触发器

开始时宣告：“正在使用 pythia-package——先设计规范，再编写主体。”

**阶段：**了解 → 提问 → 执行——先了解邻近代码和调用方，商定契约，再将规范和主体分别写入两个文件

pythia-write 能让新代码与代码库中的代码风格完全一致。这项技能会补充代码库可能未体现的内容：如何构造一个单元，让调用方可以信赖它。当项目惯例另有规定时，以项目惯例为准——先看 .pythia/conventions.md，再看 reference/plsql-standards.md 中未作规定的部分。

铁律

THE SPEC IS A CONTRACT: DESIGN IT FIRST, AND NEVER BREAK IT SILENTLY

规范变更会立即使所有依赖项失效；主体变更则不会使任何内容失效。这种不对称性决定了大部分设计选择。

工作流程

1. 了解——对最相关的两三个对象运行 pythia similar <NAME> 和 pythia src；对要调用的每个单元运行 pythia args；如果包已存在，运行 pythia impact <PKG>（规范变更会影响包中的所有内容）；对涉及的每张表运行 pythia cols。
2. 设计契约（行为尚不明确时，先使用 pythia-spec）：
   • 优先使用包，而非独立单元，除非项目惯例采用独立单元：这样可实现封装、使用私有辅助程序，并确保主体变更不会使任何依赖项失效。
   • 公共接口只包含调用方需要的内容。其他内容一律私有，仅放在主体中。新增公共项放在规范的末尾——在依赖跟踪粒度较细的版本（11g+）中，现有依赖项会保持 VALID。
   • 参数以 %TYPE 为准；默认使用 IN；仅过程可使用 OUT；大型 IN OUT 集合和 LOB 使用 NOCOPY；仅对真正可选的输入设置默认值。
   • 函数只返回一个值，不含 OUT 参数，并且在可从 SQL 调用时不得执行 DML。
   • 错误契约：在规范中声明具名异常，或为每个包规定一个有文档说明的 -20xxx 错误码范围；调用方必须能区分“未找到”和“发生故障”。
   • 事务契约：由最外层调用方提交。会执行提交的单元必须在名称或规范注释中说明这一点——此类单元无法组合到更大的事务中。
   • 日志记录／插桩通过项目的日志记录器完成；对于长时间运行的入口点，使用 DBMS_APPLICATION_INFO.SET_MODULE/SET_ACTION，以便 DBA 查看正在运行的内容。
   • 安全性：除非规范需要调用方权限，否则使用 AUTHID DEFINER；内部辅助程序使用 ACCESSIBLE BY（12c）；任何传入动态 SQL 的标识符都必须经过 DBMS_ASSERT 处理；代码中不得包含凭据。
3. 编写两个文件——先写规范，再写主体（每个对象单独一个文件，以 / 结尾；越南语消息使用 pythia unistr）。模板见 reference/plsql-standards.md；注释使用 pythia-comment。
4. 触发器保持精简：仅处理派生和审计——不包含业务流程，不执行 COMMIT，也不调用远程系统。同一张表有多个触发时机时，使用一个复合触发器（也可借此解决 ORA-04091，即表变异问题）。应将业务规则放在触发器本应调用的 API 包中。
5. 检查——运行 pythia lint spec.sql body.sql，然后运行 pythia-review。
6. 提交——先提交规范，再提交主体：运行 pythia deploy spec.sql body.sql（一次审批，按顺序部署），或分两次运行 pythia apply。退出码 3 表示失败，绝不表示完成。
7. 验证——运行 pythia errors <PKG>；对照基线运行 pythia invalid；运行 pythia plscope <PKG>，检查未使用或从未赋值的标识符。

危险信号 — 如果发现自己有以下想法，请停下来

想法	实际情况
“我只要给现有过程加个参数就行”	所有调用方都会出错或需要重新编译。添加重载，或在规范末尾添加一个新单元。
“WHEN OTHERS THEN log; 就够了”	不使用 RAISE，调用方会以为操作成功了。先记录日志，再重新抛出异常。
“最后加个 COMMIT，这样更安全”	这样就没人能在自己的事务中调用它了。提交由调用方负责。
“把这条规则放在触发器里最简单”	也最难查找、测试，以及在修复数据时绕过。应放在 API 程序包中。
“PRAGMA AUTONOMOUS_TRANSACTION 可以解决变异表问题”	它会掩盖错误并读取过时数据。应使用复合触发器。
“拼接表名没问题，这是内部代码”	今天是内部代码。调用一次 DBMS_ASSERT.SQL_OBJECT_NAME 就能验证。
“标准规定了 X，代码库却采用 Y”	以代码库为准；另行提议采用 X。

何时不应使用此技能

• 在现有单元中做小幅修改 → 使用 pythia-write 即可。
• 表设计 → 使用 pythia-table。性能优化 → 使用 pythia-tune。
• 审查他人的单元 → 使用 pythia-review。