
开发工具数据库【免费下载链接】soarSQL Optimizer And Rewriter项目地址https://gitcode.com/gh_mirrors/so/soar点击查看免费下载本指南以项目自带 FAQ 文档doc/FAQ_en.md为骨架系统讲解 SOARSQL Optimizer And Rewriter在真实使用中的高频问题从依赖工具链搭建、语法错误排查、慢速分析调优到测试环境构建、vendor 依赖更新、HTML 报告推送以及如何为项目新增一条启发式规则。文中所有结论均结合仓库源码与 Makefile 任务核对读者读完后可以独立完成 SOAR 的开发环境部署与规则二次开发。一、依赖工具链从克隆代码到构建测试的全套工具SOAR 是一个 Go 编写的命令行工具开发和测试依赖一套明确的工具链。FAQ 中列出的依赖如下工具用途git从代码仓库克隆源代码go编译源码当前 Makefile 要求 Go 版本不低于 1.12见 Makefile 的go_version_check任务govendor管理第三方依赖旧版 GOPATH 模式下的 vendor 依赖管理工具docker管理测试环境SOAR 使用 Docker 一键拉起 MySQL 测试库mysql连接测试环境执行采样与验证retool管理测试工具如gometalinter.v2、revive、golangci-lint从 Makefile 的deps任务可以看出依赖装配的完整逻辑make deps该任务会依次执行bash ./deps.sh检查依赖然后通过retool sync同步retool-install.sh生成的tools.json中所列的测试工具。仓库根目录下的 deps.sh 和 retool-install.sh 即为此流程的服务脚本lint 检查由make lint触发见 Makefile其配置位于 doc/example/metalinter.json 与 doc/example/revive.toml。二、常见问题排查语法错误与运行缓慢2.1 语法错误Syntax ErrorFAQ 明确指出了两类典型语法错误来源意外的引号Unexpected quoteSQL 中出现未转义或不成对的引号如、、。SOAR 对 SQL 做分词Tokenizer与语法树解析时引号不匹配会直接导致解析失败。vitess 语法暂不支持vitess syntax not supported yetSOAR 同时使用两套 SQL 解析器——Vitess parser 与 TiDB parser。从源码 advisor/rules.go 可见q : Query4Audit{Query: sql} // vitess 语法解析不上报以 tidb parser 为主 q.Stmt, vErr sqlparser.Parse(sql) if vErr ! nil { common.Log.Warn(NewQuery4Audit vitess parse Error: %s, Query: %s, vErr.Error(), sql) } // tidb parser 语法解析 q.TiStmt, err ast.TiParse(sql, charset, collation)即 Vitess 解析失败只记 Warn 日志最终以 TiDB parser 的结果为准但仍存在双方都暂不支持的方言语法遇到此类错误可将其作为 issue 反馈。2.2 程序运行缓慢Program running slowlyFAQ 给出的根因与调优方向非常明确这也是日常使用中最常遇到的问题跨主机访问数据库实例耗时SOAR 会使用online-dsn线上环境与test-dsn测试环境进行数据采样与执行测试若两者位于不同主机访问这些实例会消耗大量时间。尤其在批量优化大量 SQL 时这一开销会被显著放大。数据采样本身耗时-samplingtrue是默认开启行为见 common/config.go配置项Sampling bool yaml:sampling开启后为给出更准确的建议会对线上数据做采样这也会增加整体分析时间。从 database/sampling.go 的SamplingData实现可以看到采样的核心机制// 计算需要泵取的数据量 wantRowsCount : 300 * common.Config.SamplingStatisticTarget ... factor : float64(wantRowsCount) / float64(tableRows) where fmt.Sprintf(where RAND() %f LIMIT %d, factor, wantRowsCount)采样量由sampling-statistic-target对应 PostgreSQL 的default_statistics_target默认 100见 common/config.go控制。实际调优建议若对实时性要求不高、只求快速出报告可关闭采样-samplingfalse若仍希望保留采样精度可调低-sampling-statistic-target来减少泵取数据量批量优化时优先使用同一主机或内网可达的测试库避免跨公网访问也可通过-sampling-condition如WHERE xxx LIMIT xxx显式指定采样条件控制采样范围见 common/config.go。另外common/config.go 还提供了allow-online-as-test允许把线上环境当测试环境与disable-version-check禁用环境版本检测等开关前者可省去独立的测试库后者在测试库版本低于线上时继续执行但官方注释明确提示不建议开启可能会导致语句执行异常。三、构建测试环境以 sakila 示例库为准FAQ 提供了标准的测试环境构建流程使用 MySQL 官方示例数据库 sakila# 创建测试数据库 wget http://downloads.mysql.com/doc/sakila-db.tar.gz tar zxf sakila-db.tar.gz cd sakila-db mysql -u root -p -f sakila-schema.sql mysql -u root -p -f sakila-data.sql # 创建测试用户 CREATE USER roothostname IDENTIFIED BY 1tsB1g3rt; GRANT ALL ON *.* TO roothostname;这套流程在仓库中有完全对应的自动化版本Makefile 的docker任务会拉起一个名为soar-mysql的 MySQL 容器并将 test/sql/init.sql.gz 挂载为初始化脚本等待最多 180 秒直到数据库就绪make docker make docker-connect # 进入容器交互式连接 sakila 库 make docker-it # 以 bash 交互模式进入容器容器默认MYSQL_ROOT_PASSWORD1tIsB1g3rt、MYSQL_DATABASEsakila映射宿主机 3306 端口并以--sql-mode 启动以放宽 SQL 模式限制。make docker还支持通过环境变量切换 MySQL 发行版与版本例如MYSQL_RELEASEpercona MYSQL_VERSION5.7 make docker见 Makefile。四、更新 vendor 中的 vitess 依赖SOAR 同时依赖 Vitess parser 与 TiDB parser 两套解析器。由于部分网络环境下govendor fetch或直接git clonevitess 仓库可能非常缓慢甚至被阻断FAQ 说明项目选择将 vitess 源码直接加入 vendor 目录。若需要更新 vitess 包需自行绕过网络限制获取源码然后执行make vitess从 Makefile 可以看到 vendor 更新任务的完整依赖关系# Update all vendor .PHONY: vendor vendor: vitess pingcap-parser即make vendor会依次执行vitess与pingcap-parser两个子任务同时更新 Vitess 与 TiDBpingcap parser的 vendor 源码。仓库的 go.mod 与 go.sum 同时声明了两套解析器依赖而 Makefile 顶部GO111MODULE:auto见 Makefile保证了在 GOPATH 模式下 vendor 优先的兼容行为。五、HTML 格式报告一条命令输出并邮件推送FAQ 给出了将 SOAR 分析结果以 HTML 报告形式输出的完整实战脚本。soar -report-type html的输出可以直接重定向到文件并借助sendmail邮件推送#!/bin/bash soar -query select * from film ./index.html ( echo To: youmailexample.com echo From: robotexample.com echo Content-Type: text/html; echo Subject: SQL Analyze Report echo cat ./index.html ) | sendmail -t这段脚本的每一条链路在源码中都有对应实现报告类型由-report-type html控制。源码 cmd/soar/tool.go 的reportTool函数在 HTML 模式下会先输出common.MarkdownHTMLHeader()即内嵌 CSS 的 HTML 头便于邮件客户端直接渲染再输出报告正文-query参数指定待分析的 SQL 文本-query支持标准输入管道与文件输入两种方式命令行行为由bats测试框架在 test/query.bats 与 test/main.bats 中覆盖验证HTML 报告使用的主题样式位于 doc/themes可通过配置切换不同主题运行时由 common/markdown.go 完成 Markdown 到 HTML 的转换所有支持的报告类型可通过soar -list-report-types查看对应 common/cases.go 的ListReportTypesgolden 文件 common/testdata/TestListReportTypes.golden 固化了输出快照。实际落地时可将上述脚本放入 crontab 定时任务实现 SQL 审核报告的周期化邮件推送。六、新增一条启发式规则完整开发流程FAQ 给出了为 SOAR 增加一条启发式heuristic规则的四个步骤这是该项目二次开发中最典型的任务。以下结合源码逐条展开6.1 在规则注册表中登记新规则在 advisor/rules.go 中定义了规则元数据结构Ruletype Rule struct { Item string json:Item // 规则代号 Severity string json:Severity // 危险等级L[0-8], 数字越大表示级别越高 Summary string json:Summary // 规则摘要 Content string json:Content // 规则解释 Case string json:Case // SQL示例 Position int json:Position // 建议所处SQL字符位置默认0表示全局建议 Func func(*Query4Audit) Rule json:- // 函数名 }新规则需要在HeuristicRules这个 map 中登记一项如NEW.001将规则代号、等级、摘要、解释、SQL 示例与检查函数绑定在一起。6.2 在启发式检查文件中实现检查函数在 advisor/heuristic.go 中新增一个func (q *Query4Audit) RuleXXX() Rule类型的检查函数。该文件已有大量现成实现可作参考例如RuleImplicitAlias规则 ALI.001见 advisor/heuristic.go通过ast.Tokenizer对 SQL 分词并检查相邻 ID 是否重复RulePrefixLike规则 ARG.001见 advisor/heuristic.go则借助sqlparser.Walk遍历 Vitess 语法树识别LIKE %xxx这类前缀模糊匹配。典型模式是先RuleOK()取默认规则再遍历 token 或语法树命中条件后返回HeuristicRules[规则代号]。6.3 编写单元测试并刷新 golden 文件在 advisor/heuristic_test.go 中为新增规则补充测试函数。随后执行 FAQ 中给出的两条 golden 更新命令make doc go test github.com/XiaoMi/soar/advisor -v -update -run TestListHeuristicRules go test github.com/XiaoMi/soar/advisor -v -update -run TestMergeConflictHeuristicRules这里的-update标志用于刷新 golden 快照文件TestListHeuristicRulesadvisor/rules_test.go通过common.GoldenDiff对比规则列表输出其快照固化在 advisor/testdata/TestListHeuristicRules.goldenTestMergeConflictHeuristicRulesadvisor/heuristic_test.go用于检测不同规则之间是否相互冲突快照在 advisor/testdata/TestMergeConflictHeuristicRules.golden。make doc任务Makefile会调用./bin/soar -list-heuristic-rules、-list-rewrite-rules、-list-report-types三个命令自动重新生成 doc/heuristic.md、doc/rewrite.md、doc/report_type.md 三份文档保证文档与代码同步。6.4 运行完整回归最后执行make dailymake dailyMakefile是一条综合流水线包含deps依赖检查、fmtgofmt 格式化、vendorvendor 同步、docker拉起测试环境、cover覆盖率统计、doc文档生成、lint静态检查、release交叉编译、install安装、test-clibats CLI 测试与clean清理等多个阶段。如果只是想快速验证可使用make daily-quickMakefile跳过 vendor 与 docker 这两个耗时环节。七、写在最后FAQ 背后的完整工作流将 FAQ 的各个问题串起来可以看到 SOAR 的完整使用与开发闭环环境准备git 克隆代码 → Go 编译 → govendor/vendor 管理依赖 → Docker 拉起 MySQL 测试环境sakila 库日常使用通过online-dsn/test-dsn连接真实环境采样后输出 markdown/html/json 等格式的报告性能调优根据主机拓扑与采样精度需求调节-sampling、-sampling-statistic-target、-sampling-condition等参数二次开发在HeuristicRules注册新规则 → 实现检查函数 → 补测试并刷新 golden →make daily全量回归。如需查看完整的配置参数说明可参考 common/config.go 中Configuration结构体的全部字段注释以及 etc/soar.yaml 示例配置文件规则的完整列表与释义可在soar -list-heuristic-rules输出及 doc/heuristic.md 中查阅。赞分享开发工具数据库【免费下载链接】soarSQL Optimizer And Rewriter项目地址https://gitcode.com/gh_mirrors/so/soar点击查看免费下载相关推荐终极指南用DisplayPlacer告别macOS多显示器配置烦恼终极指南用DisplayPlacer告别macOS多显示器配置烦恼 你是否曾为macOS外接显示器排列而烦恼每次连接多个显示器时都要手动拖拽、调整分辨率、开发工具数据库SOAR 启发式规则全解析SQL 评审引擎的 132 条内置规则体系与实战指南SOAR 启发式规则全解析SQL 评审引擎的 132 条内置规则体系与实战指南 导读 本文以 doc/heuristic.md https://link.gi开发工具数据库Moby 依赖库 go-sockaddr 全解析用运行时启发式规则精确选择 IP 地址Moby 依赖库 go sockaddr 全解析用运行时启发式规则精确选择 IP 地址 go sockaddr 是 HashiCorp 推出的 Go sock云原生容器运行时虚拟化容器编排上一篇GhostText安全特性分析内容安全策略与权限管理最佳实践下一篇Core Plot颜色与渐变系统深度解析打造视觉冲击力图表的终极指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考