API 参考
本文档提供 SQL 格式化工具的功能与实现相关技术细节。
工具配置
格式化选项
该工具支持以下配置选项：
interface FormattingOptions {
indentSize: number; // 2, 4, or 8 spaces
keywordCase: "upper" | "lower" | "preserve";
uppercaseKeywords: boolean;
uppercaseFunctions: boolean;
uppercaseDataTypes: boolean;
alignCommas: boolean;
breakBeforeBooleanOperator: boolean;
}
默认配置
const defaultOptions: FormattingOptions = {
indentSize: 2,
keywordCase: "upper",
uppercaseKeywords: true,
uppercaseFunctions: true,
uppercaseDataTypes: true,
alignCommas: false,
breakBeforeBooleanOperator: true,
};
支持的 SQL 关键字
数据操作语言（DML）
- SELECT：从表中查询数据
- INSERT：插入新记录
- UPDATE：修改现有记录
- DELETE：删除记录
数据定义语言（DDL）
- CREATE：创建数据库对象
- ALTER：修改数据库对象
- DROP：删除数据库对象
- TRUNCATE：删除表中的全部记录
数据控制语言（DCL）
- GRANT：授予权限
- REVOKE：撤销权限
事务控制
- COMMIT：保存事务更改
- ROLLBACK：撤销事务更改
- SAVEPOINT：创建保存点
支持的 SQL 函数
聚合函数
- COUNT：统计行数或非空值数量
- SUM：计算数值总和
- AVG：计算平均值
- MIN：查找最小值
- MAX：查找最大值
字符串函数
- UPPER：转换为大写
- LOWER：转换为小写
- LENGTH：获取字符串长度
- SUBSTRING：提取子字符串
- CONCAT：拼接字符串
- TRIM：移除首尾空格
日期/时间函数
- NOW：获取当前时间戳
- DATE：提取日期部分
- TIME：提取时间部分
- YEAR：提取年份
- MONTH：提取月份
- DAY：提取日期
数学函数
- ROUND：按指定小数位四舍五入
- FLOOR：向下取整
- CEIL：向上取整
- ABS：获取绝对值
- SQRT：计算平方根
- POWER：求幂
支持的数据类型
数值类型
- INT：整数值
- INTEGER：整数值
- BIGINT：大整数值
- SMALLINT：小整数值
- TINYINT：极小整数值
- DECIMAL：定点小数
- NUMERIC：定点小数
- FLOAT：浮点数
- DOUBLE：双精度浮点数
- REAL：单精度浮点数
字符串类型
- CHAR：定长字符串
- VARCHAR：变长字符串
- TEXT：大文本数据
- BLOB：二进制大对象
日期/时间类型
- DATE：日期值
- TIME：时间值
- DATETIME：日期和时间值
- TIMESTAMP：时间戳值
其他类型
- BOOLEAN：布尔值
- BIT：位值
- JSON：JSON 数据
格式化规则
缩进规则
- SELECT 子句：每列单独一行并带缩进
- FROM 子句：表名按规则缩进
- JOIN 子句：JOIN 条件使用合适缩进
- WHERE 子句：条件按规则缩进
- GROUP BY：分组列带缩进
- ORDER BY：排序列带缩进
大小写转换规则
- 关键字：转换为指定大小写（大写/小写/保持原样）
- 函数：函数名转换为指定大小写
- 数据类型：数据类型名转换为指定大小写
- 标识符：表名和列名保持原始大小写
换行规则
- 主要子句：在 SELECT、FROM、WHERE、GROUP BY、ORDER BY 前换行
- JOIN 子句：每种 JOIN 类型前换行
- 布尔运算符：启用时在 AND/OR 前换行
- 逗号对齐：启用时在 SELECT 列表中对齐逗号
历史记录管理
历史记录结构
interface HistoryRecord {
id: string;
input: string;
output: string;
options: FormattingOptions;
timestamp: number;
}
历史记录操作
- 添加记录：自动添加新的格式化记录
- 删除记录：移除指定历史条目
- 清空历史：删除全部历史记录
- 加载记录：从历史中恢复 SQL 与选项
存储限制
- 最大记录数：50 条历史记录
- 存储位置：浏览器本地存储
- 持久性：数据在浏览器会话间保留
错误处理
常见错误
- SQL 语法无效：SQL 查询格式错误
- 不受支持的结构：格式化器不支持的 SQL 特性
- 大型查询：超过处理限制的查询
- 浏览器限制：本地存储或内存限制
错误恢复
- 语法校验：基础 SQL 语法检查
- 优雅降级：为复杂查询提供部分格式化
- 用户反馈：清晰的错误提示和建议
- 回退方案：提供替代格式化方式
性能考虑
处理限制
- 查询大小：支持最多 10,000 个字符的查询
- 复杂度：支持最多 10 层嵌套查询
- 处理时间：通常可在 100ms 内完成处理
优化特性
- 增量处理：只处理发生变化的部分
- 缓存：对重复操作缓存格式化结果
- 延迟加载：按需加载历史记录
浏览器兼容性
支持的浏览器
- Chrome：80+ 版本
- Firefox：75+ 版本
- Safari：13+ 版本
- Edge：80+ 版本
所需特性
- ES6 支持：箭头函数、模板字符串
- Local Storage：浏览器本地存储 API
- Clipboard API：现代剪贴板访问能力
- CSS Grid：布局支持
集成
嵌入选项
该工具可集成到其他应用中：
- Iframe 嵌入：以 iframe 方式嵌入
- API 集成：直接使用格式化函数
- 组件集成：作为 Vue 组件引入
自定义
- 主题支持：浅色与深色主题
- 语言支持：多语言选项
- 自定义样式：支持 CSS 样式定制