Skip to content

Commit

Permalink
Important features before updating v1.2.2
Browse files Browse the repository at this point in the history
  • Loading branch information
@CorvusYe
CorvusYe committed Jul 27, 2024
1 parent 26bbb64 commit 8721b22
Show file tree
Hide file tree
Showing 24 changed files with 788 additions and 248 deletions.
16 changes: 8 additions & 8 deletions docs/.vitepress/cache/deps/_metadata.json
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,41 @@
{
"hash": "d2c99fb3",
"browserHash": "97749c07",
"hash": "781a7085",
"browserHash": "be614ef1",
"optimized": {
"vue": {
"src": "../../../../node_modules/vue/dist/vue.runtime.esm-bundler.js",
"file": "vue.js",
"fileHash": "6067efec",
"fileHash": "60cd4b44",
"needsInterop": false
},
"vitepress > @vue/devtools-api": {
"src": "../../../../node_modules/.pnpm/@[email protected]/node_modules/@vue/devtools-api/lib/esm/index.js",
"file": "vitepress___@vue_devtools-api.js",
"fileHash": "fb8c79c3",
"fileHash": "8aa91583",
"needsInterop": false
},
"vitepress > @vueuse/integrations/useFocusTrap": {
"src": "../../../../node_modules/.pnpm/@[email protected][email protected][email protected]/node_modules/@vueuse/integrations/useFocusTrap.mjs",
"file": "vitepress___@vueuse_integrations_useFocusTrap.js",
"fileHash": "c66bc33c",
"fileHash": "8d823c88",
"needsInterop": false
},
"vitepress > mark.js/src/vanilla.js": {
"src": "../../../../node_modules/.pnpm/[email protected]/node_modules/mark.js/src/vanilla.js",
"file": "vitepress___mark__js_src_vanilla__js.js",
"fileHash": "598cd587",
"fileHash": "08d4bc64",
"needsInterop": false
},
"vitepress > minisearch": {
"src": "../../../../node_modules/.pnpm/[email protected]/node_modules/minisearch/dist/es/index.js",
"file": "vitepress___minisearch.js",
"fileHash": "9a248a67",
"fileHash": "2cad61f5",
"needsInterop": false
},
"@theme/index": {
"src": "../../../../node_modules/.pnpm/[email protected]/node_modules/vitepress/dist/client/theme-default/index.js",
"file": "@theme_index.js",
"fileHash": "c845442c",
"fileHash": "78f7c416",
"needsInterop": false
}
},
Expand Down
18 changes: 17 additions & 1 deletion docs/.vitepress/config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,14 @@ export default withMermaid({
{ text: "准备工作", link: "/dev-example/prepare" },
{ text: "使用基类读写", link: "/dev-example/dao-basic" },
{ text: "基类实现多标签", link: "/dev-example/multi-tag" },
{ text: "自定义nGQL", link: "/dev-example/custom-crud" },
{
text: "自定义nGQL",
link: "/dev-example/custom-crud",
items: [
{ text: "引用nGQL片段", link: "/dev-example/referencing-fragment" },
{ text: "多个图空间", link: "/dev-example/multi-space" },
],
},
{ text: "如何传入参数", link: "/dev-example/parameter-use" },
{ text: "不同返回值类型", link: "/dev-example/result" },
{ text: "内置返回值类型", link: "/dev-example/result-built-in" },
Expand Down Expand Up @@ -92,6 +99,15 @@ export default withMermaid({
{ text: "Using Base Class for Read and Write", link: "/en/dev-example/dao-basic" },
{ text: "Base Class Implementation for Multiple Tags", link: "/en/dev-example/multi-tag" },
{ text: "Custom nGQL", link: "/en/dev-example/custom-crud" },

{
text: "Custom nGQL",
link: "/dev-example/custom-crud",
items: [
{ text: "Referencing an nGQL Fragment", link: "/en/dev-example/referencing-fragment" },
{ text: "Multi Space", link: "/dev-example/multi-space" },
],
},
{ text: "How to Pass Parameters", link: "/en/dev-example/parameter-use" },
{ text: "Different Return Value Types", link: "/en/dev-example/result" },
{ text: "Built-in Return Value Types", link: "/en/dev-example/result-built-in" },
Expand Down
91 changes: 55 additions & 36 deletions docs/dev-example/built-in-function.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# NgBatis 内置函数与变量
# Ngbatis内置函数与变量

## 如何使用内置函数与变量

Expand All @@ -9,6 +9,7 @@ public interface PersonDao {
void insertPerson( Person person );
}
```

```xml
<mapper namespace="your.domain.PersonDao">

Expand All @@ -27,102 +28,120 @@ public interface PersonDao {
</mapper>
```

> 此处用到了 `ng.kv`、`ng.id`、`ng.tagName`、`ng.join`、`ng.schemaFmt` 等内置函数，用到了 `ng_args` 内置参数。
> 了解了使用的地方之后，咱们再往下的内容中，将对函数进一步介绍。
> 此出用到了 `ng.kv`、`ng.id`、`ng.tagName`、`ng.join`、`ng.schemaFmt`等内置函数，用到了`ng_args`内置参数。
> 了解了使用的地方之后，咱们在往下的内容中，将对函数进一步介绍。
## 内置变量

- ng_cm ClassModel DAO 接口的类模型，便于在 XML 中拿到更多类信息 (1.1.0-rc)
- ng_mm MethodModel DAO 接口中某个方法的模型，便于在 XML 中拿到方法信息，包括入参类型 (1.1.0-rc)
- ng_args 传入 DAO 接口的原始参数，未序列化前 (1.1.0-rc)
- ng_cm ClassModel Dao接口的类模型，便于在xml中拿到更多类信息 (1.1.0-rc)
- ng_mm MethodModel Dao接口中某个方法的模型，便于在xml中拿到方法信息，包括入参类型。(1.1.0-rc)
- ng_args 传入Dao接口的原始参数，未序列化前。(1.1.0-rc)

## 内置函数

- ng.valueFmt，对不定类型的数据值进行格式化，忽略是否追加单引号及日期格式化，直接传原始 Java 类型即可
- ng.valueFmt
> 对不定类型的数据值进行格式化，忽略是否追加单引号及日期格式化，直接传原始 java类型即可
参数位 | 参数说明 | 类型 | 是否必传 | 默认值
---|---|---|---|---
1 | 值 | Object | Y |
2 | 如果是字符串是否在前后追加 .* 形成模糊查询 | Boolean | N | false

1 | 值 | Object | Y |
2 | 如果是字符串是否在前后追加 .* 形成模糊查询 | boolean | N | false
> 自 v1.1.2 起，默认对字符串类型进行转义，可使用：`ValueFmtFn.setEscape( false )` 进行关闭
- ng.schemaFmt，对模式名前后追加 **`**，以避免与数据库关键字冲突
- ng.schemaFmt
> 对模式名前后追加 **`**，以避免与数据库关键字冲突
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 模式名，如 tagName, edgeName, propertyName | Object | Y

- ng.tagName，用于从实体类或 DAO 接口获取 tag name
- ng.tagName
> 用于从实体类或Dao接口获取 tag name
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 与 Schema 对应的实体类对象 | Object | Y
1 | 与Schema对应的实体类对象 | Object | Y
2 | 类模型，使用 `ng_cm` 传入 | ClassModel | N | null

- ng.pkField，用于获取主键属性，java.lang.reflect.Field
- ng.pkField
> 用于获取 主键属性，java.lang.reflect.Field
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 实体类类型 | Class<?> | Y
1 | 实体类类型 | Class<?> | Y
2 | 如果不存在主键是否报错中断 | Boolean | N | false

- ng.pkName，用于获取主键名，String
- ng.pkName
> 用于获取 主键名，String
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 实体类对象 | Object | Y
1 | 实体类对象 | Object | Y
2 | true 时使用列名，false 时使用属性名 | Boolean | N | true

- ng.entityType，用于获取实体类类型
- ng.entityType

> 用于获取实体类类型
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 实体类对象 | Object | Y
1 | 实体类对象 | Object | Y

- ng.fieldNames，获取属性名集合（不包括主键）
- ng.fieldNames
> 获取属性名集合（不包括主键）
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 实体类对象 | Object | Y
1 | 实体类对象 | Object | Y
2 | true 时使用列名，false 时使用属性名 | Boolean | N | true

- ng.id，获取 ID 值
- ng.id
> 获取id值
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 实体类对象 | Object | Y
1 | 实体类对象 | Object | Y
2 | 如果不存在主键是否报错中断 | Boolean | N | true
3 | 如果值为空，true 会通过主键生成器返回新值，false 时返回空 | Boolean | N | true
3 | 如果值为空，true会通过主键生成器返回新值，false 时 返回空 | Boolean | N | true

- ng.kv，通过实体对象或者获取多个集合
- columns 列名集合
- valueNames 属性名集合
- values 值集合
- types 属性类型
- ng.kv
> 通过实体对象或者获取多个集合
>
> - columns 列名集合
> - valueNames 属性名集合
> - values 值集合
> - types 属性类型
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 实体类对象 | Object | Y
1 | 实体类对象 | Object | Y
2 | 参数名前缀 | String | N | null
3 | 是否排除主键 | Boolean | N | true
4 | 是否排除空值 | Boolean | N | true
5 | 如无主键，是否报错中断 | Boolean | N | true

- ng.join，对集合进行格式化
- ng.join
> 对集合进行格式化
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 待格式化的集合 | Iterable | Y
2 | 元素间的分隔符 | String | N | `,`
1 | 待格式化的集合 | Iterable | Y
2 | 元素间的分隔符 | String | N | `,`
3 | 函数名，各元素拼接前，可进行函数名指定的格式化函数先行格式化，再拼接 | String | N | null

- ng.ifStringLike，类型为字符串时，前后拼接 `.*`
- ng.ifStringLike
> 类型为字符串时，前后拼接 `.*`
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|---|---|---|---
1 | 值 | Object | Y
1 | 值 | Object | Y
2 | 属性类型 | Object | N | null
3 | 属性名，用于不将值明文写在 nGQL 中，而使用参数名，让 NebulaGraph 在参数中取值 | String | N | null
3 | 属性名，用于不将值明文写在 ngql 中，而使用参数名，让 nebula 在参数中取值 | String | N | null

- ng.include
> 引用nGQL片段
参数位 | 参数说明 | 类型 | 必传 | 默认值
---|-------------------------------------------------------------------------------------------|---------|---|---
1 | 要引用的nGQL片段ID.<br/>引用其他mapper的nGQL片段，片段ID前需要加上片段所在的namespace，例：your.domain.TestDao.nGQL-ID | String | Y
2 | 引用nGQL片段时额外的参数，在生成语句时优先使用额外参数 | Object | N | null
56 changes: 28 additions & 28 deletions docs/dev-example/custom-crud.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,31 @@
# 自定义 nGQL

使用此方式的时候，对 nGQL、Cypher 的熟悉度要求会高一些。还不太熟悉的开发者，可以通过【[什么是 nGQL](https://docs.nebula-graph.com.cn/3.1.0/3.ngql-guide/1.nGQL-overview/1.overview/)】进行了解。

另外提一下：这边使用的模板引擎是 Beetl：

- [Beetl 官方文档](https://www.kancloud.cn/xiandafu/beetl3_guide/2138947)，主要看占位符。NgBatis 已经做好了变量设置，如果只是参数填充，可以忽略定界符的使用。【例子详见[“如何传入参数”](./parameter-use)】。其实，参数条件控制跟参数循环定界符几乎不可避免。因 `NgBatis` 关于 `Beetl` 配置的差异，文档中如涉及界定符，则由文档中的 **<% %>** 替换成 **@ \n**，如：
```diff
- <%if ( aBool ) {
-
- } %>
+ @if ( aBool ) {
+
+ @}
```
- [Beetl 文档-用于处理参数的函数](https://www.kancloud.cn/xiandafu/beetl3_guide/2138956)
- [Beetl 文档-条件控制](https://www.kancloud.cn/xiandafu/beetl3_guide/2138953)，【例子详见[“参数条件控制”](./parameter-if)】
- [Beetl 文档-循环语句](https://www.kancloud.cn/xiandafu/beetl3_guide/2138952)，【例子详见[“参数遍历”](./parameter-for)】
- [Beetl 在线测试小工具](http://ibeetl.com/beetlonline/)


与[“使用基类读写”](./dao-basic)相同，需要编写一个 `XXXDao.java` 文件与 `XXXDao.xml` 文件。
# 自定义nGQL

- > 使用此方式的时候，对 nGQL、cypher 的熟悉度要求会高一些。还不太熟悉的开发者，可以通过【[什么是nGQL](https://docs.nebula-graph.com.cn/3.1.0/3.ngql-guide/1.nGQL-overview/1.overview/)】进行了解。
- > 另外提一下：这边使用的模板引擎是Beetl
>
> - [Beetl官方文档](https://www.kancloud.cn/xiandafu/beetl3_guide/2138947)，主要看占位符。ngbatis已经做好了变量设置，如果只是参数填充，可以忽略定界符的使用。
【例子详见[如何传入参数](./parameter-use)】
但，参数条件控制跟参数循环定界符几乎不可避免。因`ngbatis`关于`beetl`配置的差异，文档中如涉及界定符，则由文档中的 <% %> 替换成 @ \n，如：
>
> ```diff
> - <%if ( aBool ) {
> -
> - } %>
> + @if ( aBool ) {
> +
> + @}
> ```
>
> - [Beetl文档-用于处理参数的函数](https://www.kancloud.cn/xiandafu/beetl3_guide/2138956)
> - [Beetl文档-条件控制](https://www.kancloud.cn/xiandafu/beetl3_guide/2138953)【例子详见[参数条件控制](./parameter-if)】
> - [Beetl文档-循环语句](https://www.kancloud.cn/xiandafu/beetl3_guide/2138952)【例子详见[参数遍历](./parameter-for)】
> - [Beetl在线测试小工具](http://ibeetl.com/beetlonline/)
与[使用基类读写](./dao-basic)相同，需要编写一个 XXXDao.java 文件与 XXXDao.xml 文件。
## 新建文件
### 创建一个 Person 对应的 DAO，如果不需要用到基类方法，可以不继承 NebulaDaoBasic
### 创建一个Person对应的Dao，如果不需要用到基类方法，可以不继承 NebulaDaoBasic
```java
package your.domain;
Expand All @@ -45,22 +47,20 @@ public interface PersonDao {
```

> XXXDao.java 无需经过 @Mapper 或者 @Component 进行注解，而是通过 namespace 进行发现，并自动注册成 Bean。
> 前提是：namespace 需要在 @SpringBootApplication 注解下的 scanBasePackages 值中。
> 如：@SpringBootApplication( scanBasePackages = { "your.domain", "org.nebula.contrib" } )
## 如何让 Java 程序通过 NgBatis 执行 nGQL | Cypher
## 如何让 java 程序通过 ngbatis 执行 nGQL | cypher

### 以一个简单的查询语句为例：
### 以一个简单的查询语句为例

#### 在 PersonDao.java 中追加接口

```java
Integer select1();
```

> 目前版本中，接口的返回值类型与方法参数类型，如果是基本类型，仅支持 Java 包装类，如 int 请写成 Integer。
> 目前版本中，接口的返回值类型与方法参数类型，如果是基本类型，仅支持包装类，如 int 请写成 Integer。
#### 在 PersonDao.xml 中新增一个标签

Expand Down
4 changes: 2 additions & 2 deletions docs/dev-example/dao-basic.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,12 @@ public class PersonServiceImpl {

@Autowired private PersonDao dao;

// 不管属性是否为空，如果数据库中已有对应 ID 的值，则覆盖
// 全属性写入，如果对应的 id 已存在，放弃写入
public void insert( Person person ) {
dao.insert( person );
}

// 仅写入非空属性
// 仅写入非空属性，如果对应的 id 已存在，放弃写入
public void insertSelective( Person preson ) {
dao.insertSelective( person );
}
Expand Down
35 changes: 35 additions & 0 deletions docs/dev-example/multi-space.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# 多个图空间

## 固定空间

- 在实体类中追加 @Space("myspace") 指定 tag 所属空间
- 在xml的mapper标签中

```xml
<!-- 优先级要高于 yml 连接参数中指定的 space -->
<mapper namespace="your.domain.PersonDao" space="test">

</mapper>
```

- 在接口方法的标签中指定 space，如：

```xml
<mapper namespace="your.domain.PersonDao" space="test">

<!-- 优先级要高于 mapper 中的 test -->
<select id="spaceFromParam" space="test2">
RETURN true;
</select>

</mapper>
```

## 动态空间 （^1.2.2）

```xml
<select id="spaceFromParam" space="${paramMySpace}" spaceFromParam="true">
RETURN true;
</select>
```
> paramMySpace通过接口的参数传入。
Loading

0 comments on commit 8721b22

Please sign in to comment.