企业官网建设流程全解析

• 静态分析
• SAST
• 应用安全
• 漏洞扫描
• 代码质量

本文基于 CodeQL 仓库中 C# QL 库的版本变更日志 csharp/ql/lib/change-notes/released/0.0.11.md，完整解读 0.0.11 版本引入的两项破坏性变更：C# 提取器对九个遗留环境变量的支持被彻底移除，以及codeql test run开始从子目录递归提取源代码。读完后，你可以明确升级该版本后需要修改哪些提取器调用脚本与环境变量，并能预判既有测试套件为何会因嵌套目录结构而失败。

版本定位：一次纯粹的“清理型”发布

csharp/ql/lib下的 C# 数据库库采用按版本号命名的变更日志文件来记录每个发布版本的差异，0.0.11 的变更日志位于 csharp/ql/lib/change-notes/released/0.0.11.md，其内容同时被收录进汇总的 CHANGELOG.md。该版本没有任何新功能或分析改进，全部篇幅都是 Breaking Changes（破坏性变更），共两条：

1. C# 提取器不再支持一组遗留（legacy）环境变量；
2. codeql test run现在会从子文件夹递归提取源代码。

这两条变更的共同主题，是把提取器从早期 Semmle/ODASA 时代的命名约定，迁移到统一的CODEQL_*命名规范之下，并让测试框架的源文件收集范围与真实构建行为保持一致。

破坏性变更一：九个遗留环境变量被移除

变更日志原文列出了不再受支持的九个环境变量（此处完整保留原清单）：

ODASA_BUILD_ERROR_DIR ODASA_CSHARP_LAYOUT ODASA_SNAPSHOT SEMMLE_DIST SEMMLE_EXTRACTOR_OPTIONS SEMMLE_PLATFORM_TOOLS SEMMLE_PRESERVE_SYMLINKS SOURCE_ARCHIVE TRAP_FOLDER

这些变量分别带有ODASA_、SEMMLE_前缀或是无命名空间前缀的裸名，属于提取器早期版本的接口。自 0.0.11 起，提取器读取它们将不再产生任何效果——如果你在 CI 脚本、Docker 镜像或自建构建工具中仍然导出这些变量，升级后提取行为会静默改变，且不会有任何告警提示。

当前的环境变量命名规范

从源码结构看，现版本的环境变量已经统一收敛到CODEQL_前缀之下，并且按“平台级 + 语言级”两层组织。C# autobuilder 共享库中的 EnvVars.cs 给出了当前的权威清单：

public const string Platform = "CODEQL_PLATFORM"; public static string Root(Language language) => $"CODEQL_EXTRACTOR_{language.UpperCaseName}_ROOT"; public static string TrapDir(Language language) => $"CODEQL_EXTRACTOR_{language.UpperCaseName}_TRAP_DIR"; public static string SourceArchiveDir(Language language) => $"CODEQL_EXTRACTOR_{language.UpperCaseName}_SOURCE_ARCHIVE_DIR"; public static string DiagnosticDir(Language language) => $"CODEQL_EXTRACTOR_{language.UpperCaseName}_DIAGNOSTIC_DIR";

对 C# 而言，语言级变量的具体取值即CODEQL_EXTRACTOR_CSHARP_ROOT、CODEQL_EXTRACTOR_CSHARP_TRAP_DIR、CODEQL_EXTRACTOR_CSHARP_SOURCE_ARCHIVE_DIR、CODEQL_EXTRACTOR_CSHARP_DIAGNOSTIC_DIR。

提取器本体同样印证了这一约定。PathTransformer.cs 中，生成 TRAP 文件路径与创建 TRAP 写入器时，直接读取的是：

Environment.GetEnvironmentVariable("CODEQL_EXTRACTOR_CSHARP_TRAP_DIR") Environment.GetEnvironmentVariable("CODEQL_EXTRACTOR_CSHARP_SOURCE_ARCHIVE_DIR")

旧变量到新变量的对应关系

对照上表与源码中的实际取值，可以推断出移除清单与现行变量之间的大致迁移对应关系，供升级时逐项替换参考：

其中 TRAP 目录、源归档目录两组对应关系有源码取值直接佐证；其余几项的映射是从源码结构推断的，若你的流水线中有对应依赖，建议以当前仓库中 Semmle.Util 与 Extractor 的实际读取点为准逐一核实。

破坏性变更二：codeql test run递归提取子文件夹

变更日志第二条原文为：

codeql test runnow extracts source code recursively from sub folders. This may break existing tests that have other tests in nested sub folders, as those will now get the nested test code included.

含义是：codeql test run在为某个测试建立数据库时，源文件收集范围从“仅测试根目录”扩大为“递归包含所有子文件夹”。由此带来的破坏性在于——如果测试目录中嵌套了另一个测试的文件夹，外层测试在提取时会把内层测试的源代码一并纳入数据库。这会导致：

• 原本不会命中的警报出现在外层测试的.expected文件中，测试结果与期望不符而失败；
• 数据库规模增大，测试运行时间变长。

C# 语言的测试目录 csharp/ql/test 采用了library-tests、query-tests、shared、resources等并列子目录的组织方式。升级后，若某类测试把自己的测试用例文件平铺在根目录之下、且子目录中存放了其他用途的 C# 代码，就应检查该测试在递归提取下是否仍然成立，必要时应重新整理目录层级或更新对应的.expected期望文件。

升级检查清单

结合上述两条变更，升级 C# 数据库库到 0.0.11 及以上版本时，建议按以下顺序自查：

1. 全局搜索构建脚本、CI 配置与 Docker 文件中是否仍导出ODASA_、SEMMLE_前缀变量及裸名TRAP_FOLDER、SOURCE_ARCHIVE；
2. 将 TRAP 输出与源归档路径统一替换为CODEQL_EXTRACTOR_CSHARP_TRAP_DIR、CODEQL_EXTRACTOR_CSHARP_SOURCE_ARCHIVE_DIR；
3. 检查csharp/ql/test下各测试的目录结构，确认嵌套子目录不会把“别人的测试代码”提取进当前测试的数据库；
4. 回归运行受影响的测试，按递归提取后的真实结果修订.expected期望文件。

延伸阅读

• 变更日志条目：csharp/ql/lib/change-notes/released/0.0.11.md
• 汇总变更日志：csharp/ql/lib/CHANGELOG.md
• 现行环境变量定义：csharp/autobuilder/Semmle.Autobuild.Shared/EnvVars.cs
• 路径变换与 TRAP 目录读取实现：csharp/extractor/Semmle.Extraction.CSharp/Extractor/PathTransformer.cs
• C# 测试目录：csharp/ql/test

• 静态分析
• SAST
• 应用安全
• 漏洞扫描
• 代码质量