You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by ni...@apache.org on 2018/12/18 02:39:19 UTC
[servicecomb-pack] branch master updated: Update the user_guild
document
This is an automated email from the ASF dual-hosted git repository.
ningjiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-pack.git
The following commit(s) were added to refs/heads/master by this push:
new 325d0a5 Update the user_guild document
325d0a5 is described below
commit 325d0a5e97fd04186acc8ed2cdcbbeeb4b0237d9
Author: Willem Jiang <ji...@huawei.com>
AuthorDate: Tue Dec 18 10:38:55 2018 +0800
Update the user_guild document
---
docs/user_guide.md | 84 ++++++++++++++++++++++++++++++++++++++++++---------
docs/user_guide_zh.md | 80 ++++++++++++++++++++++++++++++++++++++++--------
2 files changed, 137 insertions(+), 27 deletions(-)
diff --git a/docs/user_guide.md b/docs/user_guide.md
index 9fe4f5f..ef2f198 100644
--- a/docs/user_guide.md
+++ b/docs/user_guide.md
@@ -1,4 +1,4 @@
-# Saga User Guide
+# Pack User Guide
[](user_guide_zh.md)
## Prerequisites
@@ -15,8 +15,8 @@ You will need:
Retrieve the source code:
```bash
-$ git clone https://github.com/apache/servicecomb-saga.git
-$ cd servicecomb-saga
+$ git clone https://github.com/apache/servicecomb-pack.git
+$ cd servicecomb-pack
```
Saga can be built in either of the following ways.
@@ -38,22 +38,23 @@ Saga can be built in either of the following ways.
After executing either one of the above command, you will find alpha server's executable file in `alpha/alpha-server/target/saga/alpha-server-${version}-exec.jar`.
## How to use
-### Add saga dependencies
+### Add pack dependencies
```xml
<dependency>
- <groupId>org.apache.servicecomb.saga</groupId>
+ <groupId>org.apache.servicecomb.pack</groupId>
<artifactId>omega-spring-starter</artifactId>
- <version>${saga.version}</version>
+ <version>${pack.version}</version>
</dependency>
<dependency>
- <groupId>org.apache.servicecomb.saga</groupId>
+ <groupId>org.apache.servicecomb.pack</groupId>
<artifactId>omega-transport-resttemplate</artifactId>
- <version>${saga.version}</version>
+ <version>${pack.version}</version>
</dependency>
```
-**Note**: Please change the `${saga.version}` to the actual version.
+**Note**: Please change the `${pack.version}` to the actual version. Since 0.3.0 we update the package name of
-### Add saga annotations and corresponding compensation methods
+### Saga Support
+Add saga annotations and corresponding compensation methods
Take a transfer money application as an example:
1. add `@EnableOmega` at application entry to initialize omega configurations and connect to alpha
```java
@@ -79,16 +80,19 @@ Take a transfer money application as an example:
3. add `@Compensable` at the sub-transaction and specify its corresponding compensation method
```java
@Compensable(timeout=5, compensationMethod="cancel")
+ @Transactional
public boolean transferOut(String from, int amount) {
repo.reduceBalanceByUsername(from, amount);
}
+ @Transactional
public boolean cancel(String from, int amount) {
repo.addBalanceByUsername(from, amount);
}
```
- **Note** transactions and compensations implemented by services must be idempotent.
+ **Note** The transactions and compensations method should have same arguments. The transactions and compensations implemented by services must be idempotent. We highly recommend to use the Spring @Transactional to guarantee the local transaction.
+
**Note:** By default, timeout is disable.
@@ -96,14 +100,66 @@ Take a transfer money application as an example:
4. Repeat step 3 for the `transferIn` service.
-5. Since Saga-0.3.0, you can access the [OmegaContext](https://github.com/apache/servicecomb-saga/blob/master/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/OmegaContext.java) for the gloableTxId and localTxId in the @Compensable annotated method or the cancel method.
+5. Since pack-0.3.0, you can access the [OmegaContext](https://github.com/apache/servicecomb-packblob/master/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/OmegaContext.java) for the gloableTxId and localTxId in the @Compensable annotated method or the cancel method.
+
+### TCC support
+Add TCC annotations and corresponding confirm and cancel methods
+ Take a transfer money application as an example:
+ 1. add `@EnableOmega` at application entry to initialize omega configurations and connect to alpha
+ ```java
+ @SpringBootApplication
+ @EnableOmega
+ public class Application {
+ public static void main(String[] args) {
+ SpringApplication.run(Application.class, args);
+ }
+ }
+ ```
+
+ 2. add `@TccStart` at the starting point of the global transaction
+ ```java
+ @TccStart
+ public boolean transferMoney(String from, String to, int amount) {
+ transferOut(from, amount);
+ transferIn(to, amount);
+ }
+ ```
+ **Note:** By default, timeout is disable.
+
+ 3. add `@Participate` at the sub-transaction and specify its corresponding compensation method
+ ```java
+ @Participate(confirmMethod = "confirm", cancelMethod = "cancel")
+ @Transactional
+ public void transferOut(String from, int amount) {
+ // check banalance
+ }
+
+ @Transactional
+ public void confirm(String from, int amount) {
+ repo.reduceBalanceByUsername(from, amount);
+ }
+
+ @Transactional
+ public void cancel(String from, int amount) {
+ repo.addBalanceByUsername(from, amount);
+ }
+ ```
+
+ **Note:** The confirm and cancel method should have same arguments with participate method, confirm and cancel method implemented by services must be idempotent. We highly recommend to use the Spring @Transactional to guarantee the local transaction.
+
+ **Note:** Current TCC implementation doesn't support timeout.
+
+ **Note:** If the starting point of global transaction and local transaction overlaps, both `@TccStart` and `@Participate` are needed.
+
+ 4. Repeat step 3 for the `transferIn` service.
+
## How to run
1. run postgreSQL.
```bash
docker run -d -e "POSTGRES_DB=saga" -e "POSTGRES_USER=saga" -e "POSTGRES_PASSWORD=password" -p 5432:5432 postgres
```
- Please check out [this document](https://github.com/apache/servicecomb-saga/blob/master/docs/faq/en/how_to_use_mysql_as_alpha_backend_database.md), if you want to use the MySQL instead of postgreSQL.
+ Please check out [this document](https://github.com/apache/servicecomb-pack/blob/master/docs/faq/en/how_to_use_mysql_as_alpha_backend_database.md), if you want to use the MySQL instead of postgreSQL.
2. run alpha. Before running alpha, please make sure postgreSQL is already up. You can run alpha through docker or executable file.
* Run alpha through docker.
@@ -115,7 +171,7 @@ Take a transfer money application as an example:
java -Dspring.profiles.active=prd -D"spring.datasource.url=jdbc:postgresql://${host_address}:5432/saga?useSSL=false" -jar alpha-server-${saga_version}-exec.jar
```
- **Note**: Please change `${saga_version}` and `${host_address}` to the actual value before you execute the command.
+ **Note**: Please change `${pack_version}` and `${host_address}` to the actual value before you execute the command.
**Note**: By default, port 8080 is used to serve omega's request via gRPC while port 8090 is used to query the events stored in alpha.
diff --git a/docs/user_guide_zh.md b/docs/user_guide_zh.md
index 416244a..c9724f0 100644
--- a/docs/user_guide_zh.md
+++ b/docs/user_guide_zh.md
@@ -1,4 +1,4 @@
-# Saga 用户指南
+# Pack 用户指南
[](user_guide.md)
## 准备环境
@@ -14,8 +14,8 @@
获取源码：
```bash
-$ git clone https://github.com/apache/servicecomb-saga.git
-$ cd servicecomb-saga
+$ git clone https://github.com/apache/servicecomb-pack.git
+$ cd servicecomb-pack
```
Saga可通过以下任一方式进行构建：
@@ -38,22 +38,23 @@ Saga可通过以下任一方式进行构建：
在执行以上任一指令后，可在`alpha/alpha-server/target/saga/alpha-server-${version}-exec.jar`中找到alpha server的可执行文件。
## 如何使用
-### 引入Saga的依赖
+### 引入Pack的依赖
```xml
<dependency>
- <groupId>org.apache.servicecomb.saga</groupId>
+ <groupId>org.apache.servicecomb.pack</groupId>
<artifactId>omega-spring-starter</artifactId>
- <version>${saga.version}</version>
+ <version>${pack.version}</version>
</dependency>
<dependency>
- <groupId>org.apache.servicecomb.saga</groupId>
+ <groupId>org.apache.servicecomb.pack</groupId>
<artifactId>omega-transport-resttemplate</artifactId>
- <version>${saga.version}</version>
+ <version>${pack.version}</version>
</dependency>
```
-**注意**: 请将`${saga.version}`更改为实际的版本号。
+**注意**: 请将`${pack.version}`更改为实际的版本号。
-### 添加Saga的注解及相应的补偿方法
+### Saga 支持
+添加Saga的注解及相应的补偿方法
以一个转账应用为例：
1. 在应用入口添加 `@EnableOmega` 的注解来初始化omega的配置并与alpha建立连接。
```java
@@ -79,16 +80,18 @@ Saga可通过以下任一方式进行构建：
3. 在子事务处添加 `@Compensable` 的注解并指明其对应的补偿方法。
```java
@Compensable(timeout=5, compensationMethod="cancel")
+ @Transactional
public boolean transferOut(String from, int amount) {
repo.reduceBalanceByUsername(from, amount);
}
+ @Transactional
public boolean cancel(String from, int amount) {
repo.addBalanceByUsername(from, amount);
}
```
- **注意:** 实现的服务和补偿必须满足幂等的条件。
+ **注意:** 实现的服务使用相当的参数，实现的服务和补偿必须满足幂等的条件，同时建议使用Spring @Transactional标注提供本地事务保证。
**注意:** 默认情况下，超时设置需要显式声明才生效。
@@ -96,7 +99,58 @@ Saga可通过以下任一方式进行构建：
4. 对转入服务重复第三步即可。
-5. 从Saga-0.3.0, 你可以在服务函数或者取消函数中通过访问 [OmegaContext](https://github.com/apache/servicecomb-saga/blob/master/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/OmegaContext.java) 来获取 gloableTxId 以及 localTxId 信息。
+5. 从pack-0.3.0开始, 你可以在服务函数或者取消函数中通过访问 [OmegaContext](https://github.com/apache/servicecomb-pack/blob/master/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/OmegaContext.java) 来获取 gloableTxId 以及 localTxId 信息。
+
+### TCC 支持
+在对应的方法中添加TccStart 和 Participate标注
+ 以一个转账应用为例：
+1. 在应用入口添加 `@EnableOmega` 的注解来初始化omega的配置并与alpha建立连接。
+ ```java
+ @SpringBootApplication
+ @EnableOmega
+ public class Application {
+ public static void main(String[] args) {
+ SpringApplication.run(Application.class, args);
+ }
+ }
+ ```
+
+2. 在全局事务的起点添加 `@TccStart` 的注解。
+ ```java
+ @TccStart
+ public boolean transferMoney(String from, String to, int amount) {
+ transferOut(from, amount);
+ transferIn(to, amount);
+ }
+ ```
+ **Note:** 当前TCC还不支持Timeout
+
+3. 在子事务尝试方法处添加 `@Participate` 的注解并指明其对应的执行以及补偿方法名,
+ ```java
+ @Participate(confirmMethod = "confirm", cancelMethod = "cancel")
+ @Transactional
+ public void transferOut(String from, int amount) {
+ // check banalance
+ }
+
+ @Transactional
+ public void confirm(String from, int amount) {
+ repo.reduceBalanceByUsername(from, amount);
+ }
+
+ @Transactional
+ public void cancel(String from, int amount) {
+ repo.addBalanceByUsername(from, amount);
+ }
+ ```
+
+ **Note:** The confirm and cancel method should have same arguments with participate method, confirm and cancel method implemented by services must be idempotent. We highly recommend to use the Spring @Transactional to guarantee the local transaction.
+
+ **Note:** 若全局事务起点与子事务起点重合，需同时声明 `@TccStart` 和 `@Participate` 的注解。
+
+4. 对转入服务重复第三步即可。
+
+5. 从pack-0.3.0开始, 你可以在服务函数或者取消函数中通过访问 [OmegaContext](https://github.com/apache/servicecomb-pack/blob/master/omega/omega-context/src/main/java/org/apache/servicecomb/saga/omega/context/OmegaContext.java) 来获取 gloableTxId 以及 localTxId 信息。
## 如何运行
@@ -104,7 +158,7 @@ Saga可通过以下任一方式进行构建：
```bash
docker run -d -e "POSTGRES_DB=saga" -e "POSTGRES_USER=saga" -e "POSTGRES_PASSWORD=password" -p 5432:5432 postgres
```
- 如果你想使用MySQL做为后台数据库，可以参考 [此文档](https://github.com/apache/servicecomb-saga/blob/master/docs/faq/en/how_to_use_mysql_as_alpha_backend_database.md)。
+ 如果你想使用MySQL做为后台数据库，可以参考 [此文档](https://github.com/apache/servicecomb-pack/blob/master/docs/faq/en/how_to_use_mysql_as_alpha_backend_database.md)。
2. 运行alpha。在运行alpha前，请确保postgreSQL已正常启动。可通过docker或可执行文件的方式来启动alpha。