# Markdown文件 BeetlSQL3 默认是用Markdown格式来组织SQL文件，并且使用Beetl模板引擎来生成sql 开发者可以使用任何其他格式和喜欢的引擎来组织SQL，BeetlSQL提供插件机制。比如以xml来组织sql，sql使用freemaker模板语法,完成插件需要参考《源码解读》或者代码`SQLTemplateEngine` 本章只讨论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会优先加载特定库下的文件，实际上对于`user.select`，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片段，就优先使用。通常在sql根目录下放置公共的sql片段，然后在style你目录下放置有差异的sql片段 ## use函数 BeetlSQL3提供use函数，可以重用当前sql文件的sql片段，如下 ```markdown select === select #{use("cols")} where sys_user cols === id,name,department_id ``` use函数支持第二个参数是Map，以像sql片段传递模板参数 ```markdown select === select #{use("cols",{"extCol":"ccc"})} where sys_user where id=#{id} cols === id,name,department_id,${cc} ``` 注意，这里的cols片段使用了${},这样模板渲染直接输出文本，而不是SQL占位符? ## 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 ``` 同use函数一样，globalUse也支持Map作为第二个参数 ## 其他模板支持函数 beetlsql使用了Beetl作为模板引擎，因此你可以使用beetl的函数，也可以自定义函数。关于beetlsql支持函数，详情可以参考下一张Beetl。这里列出常用基本函数 - print、println ：输出，同js，如print("table1"); - has ： 判断是否有此全局变量; - isEmpty ： 判断表达式是否为空，不存在，空字符串，空集合都返回true; - debug ：将变量输出到控制台，如 debug(user); - text ：输出变量值本身，但可用于占位符号里 - page ：分页函数，用于在PageQuery翻页里，根据上下问决定输出count(1) 或者count(*)，如果有参数，则按照参数输出 - join ：将集合或数组内元素用逗号拼接，并输出`?` 用于占位符，用于in，如#{join(ids)} - use 参数是同一个md文件的sqlid，类似mybatis的 sql功能， - globalUse 参数是其他sql文件的Sql片段的Id，如globalUse("share.accessControl"),将访问share.md(sql)文件的accessControl片段 - db.dynamicSql 类似use功能,但第一个参数是sql片段，而不是sqlId - page函数用于翻页，动态生成* 或者count(*)