# Markdown文件 BeetlSQL3 默认是用Markdown格式来组织SQL文件,并且使用Beetl模板引擎来生成sql 开发者可以使用任何其他格式和喜欢的引擎来组织SQL,BeetlSQL提供插件机制。比如以xml来组织sql,sql使用freemaker模板语法,完成插件需要参考《源码解读》 本章只讨论Markdown文件的用法,在《使用SQLManager》和《重要:数据模型》都已经说明过,如果看了这了解,本章可以快速阅读,如果想用其他方式组织SQL,参考《BeetlSQL3源码解读》 ## 文件格式 系统默认使用MarkdownClasspathLoader 来加载sql文件。 sql文件扩展名可以是md或者sql,推荐使用md作为扩展名。所有文件默认位于classpath的sql目录下。一个sql文件对应多个sql片段,如下是一个sql文件格式 ```markdown select === select * from sys_user where id=#{id} update === update sys_user set status=1 whre id=#{id} ``` 使用`===`作为分隔,`===`上方是sql片段名称,切记名称后不要有空格或者任何不可见的符号,否则BeetlSQL找不到 markdown文件支持代码块来标识sql片段 ```markdown update === ```sql update sys_user set status=1 whre id=#{id} ```sql ``` ````sql`好处有助于IDE或者其他工具能对sql进行着色和语法校验 可以在sql片段开始处使用 `*` 作为此sql片段的注释 ```markdown update === * 更新用户状态 * 设置状态为1 ```sql update sys_user set status=1 whre id=#{id} ```sql ``` 允许在整个sql文件开头加上任意的注释 ```markdown 说明:用户操作文件,参考UserMapper select === select * from sys_user where id=#{id} update === * 更新用户状态 * 设置状态为1 ```sql update sys_user set status=1 whre id=#{id} ```sql ``` ## 组织文件 BeetlSQL3通过SqlId来引用文件,如下id标识的是user.md(sql)的select片段,id2标识的是sys目录下的user.md(sql)的select片段 ```java SqlId id = new SqlId("user","select") SqlId id2 = new SqlId("sys.user","select") ``` 考虑到跨库操作,BeetlSQL会优先加载特定库下的文件,实际上对于如下id,BeetlSQL会寻找的可能文件是(假设数据库是Mysql) * mysql/user.md * mysql/user.sql * user.md * user.sql 如果系统切换到Oralce,则BeetlSQL会寻找如下可能文件 ``` * oracle/user.md * oralce/user.sql * user.md * user.sql ``` 如果在特定数据库下找到了sql片段,就优先使用。 ## use函数 BeetlSQL3提供use函数,可以重用当前sql文件的sql片段,如下 ```markdown select === select #{use("cols")} where sys_user cols === id,name,department_id ``` ## globalUse 如果想引用其他sql文件的片段,则需要使用globalUse BeetlSQL3提供use函数,可以重用当前sql文件的sql片段,如下 ```markdown select === select #{globalUse("common.cols")} where sys_user ``` common.md包含了cols片段 ```java cols === id,name,department_id ```