Skip to content

Commit 1b6553b

Browse files
kevinten10kevinten10
committed
docs: update readme
1 parent 5a72627 commit 1b6553b

File tree

3 files changed

+350
-59
lines changed

3 files changed

+350
-59
lines changed

‎README.md‎

Lines changed: 140 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,212 @@
1+
![logo](./docs/logo.png)
2+
13
# Capa(cloud application api): To be the high-level api layer for all application runtime.
24

3-
Define a common set of APIs to make sure that code once and run anywhere!
5+
Let the code achieve "write once, run anywhere".
6+
7+
With the help of the Capa project, your Java applications have the ability to run across clouds and hybrid clouds with small changes.
8+
9+
[中文文档](./README_ZH.md)
10+
11+
## Motivation
12+
13+
### Mecha architecture
14+
15+
The Capa project is based on the design concept of the Mecha architecture and uses **rich SDK mode** to provide Multi-Runtime standard API.
16+
17+
You can simply understand the Capa project as the SDK implementation of [Dapr](https://github.com/dapr/dapr) / [Layotto](https://github.com/mosn/layotto) Sidecar mode projects.
18+
19+
To understand the design ideas of Mecha architecture, please read the following articles:
20+
21+
[死生之地不可不察：论API标准化对Dapr的重要性](https://www.infoq.cn/article/wjkNGoGaaHyKs7xIyTSB)
22+
23+
[MOSN子项目Layotto：开启服务网格+应用运行时新篇章](http://mosn.io/layotto/#/zh/blog/mosn-subproject-layotto-opening-a-new-chapter-in-service-grid-application-runtime/index)
24+
25+
### Sidecar or SDK
26+
27+
Based on the Mecha architecture concept, Multi-Runtime provides standard API functions in a Sidecar manner, which seems to be the most reasonable choice.
28+
29+
So why not use Dapr/Layotto and other projects directly, but choose to develop the Capa project of **Rich SDK Mode** instead.
30+
31+
Summary: _The Sidecar architecture represented by Dapr is the future, but it is difficult for many existing enterprises and systems to upgrade to the Sidecar architecture in one step. The rich SDK architecture will exist for a long time._
32+
33+
Extension: _Faced with the huge Java systems, the Capa project will use the rich SDK model to support the transition from the Java system to the Mecha architecture. After Dapr and other projects mature, they can also be seamlessly connected to the Sidecar architecture._
34+
35+
For specific discussions on this issue, please refer to:
36+
37+
[SDK模型的Dapr API](https://github.com/dapr/dapr/issues/3261)
38+
39+
[Dapr API的未来计划](https://github.com/dapr/dapr/issues/2817)
40+
41+
[Java SDK的设计讨论](https://github.com/mosn/layotto/issues/188)
442

5-
This is the Capa SDK for Java, including the following features:
43+
## Feature
644

7-
+ Service Invocation(RPC)
8-
+ Configuration Centor(Configuration)
9-
+ Publish/Subscribe(Pub/Sub)
10-
+ State Management(State)
11-
+ Application Metrics(Metrics)
12-
+
13-
参考项目:
45+
### API definition
1446

15-
* [dapr](https://github.com/dapr/dapr)
16-
* [layotto](https://github.com/mosn/layotto)
47+
Capa API design follow community standards, please refer to the API definitions of open source projects such as Dapr / Layotto.
1748

18-
## Introduction
49+
The API definition is placed in the following independent warehouse, unbound from the Capa project, and hopes to develop into the community's API standard definition:
1950

20-
使用与具体实现无关的统一的编程API，所以应用程序在编程时不需要依赖任何具体的基础设施和中间件，只需要依赖CAPA的抽象层SDK即可。
51+
+ java: [cloud-runtimes-jvm](https://github.com/reactivegroup/cloud-runtimes-jvm)
52+
+ python(alpha): [cloud-runtimes-python](https://github.com/reactivegroup/cloud-runtimes-python)
53+
+ golang(alpha): [cloud-runtimes-golang](https://github.com/reactivegroup/cloud-runtimes-golang)
2154

22-
在部署到不同的环境时，装载抽象SDK的不同实现到应用程序中，当调用统一的编程API时，底层适配到不同的具体实现。
55+
#### Why not use Dapr API directly?
2356

24-
所以应用程序不管将来要运行在哪里，只需要依赖一套统一的SDK就可以了。
57+
Due to the current strong binding between Dapr API and Dapr project, we hope that this set of API can become the standard of the entire community, so Capa puts the API definition in an independent warehouse and keeps it synchronized with upstream community standards at all times.
2558

26-
**参考资料：** https://github.com/dapr/dapr/issues/3261
59+
We hope that Dapr can deploy its API independently, decouple it from the Dapr project, and become a standard for the entire community.
2760

28-
### Why not DAPR
61+
For the discussion of this item, please see:
2962

30-
设计思想和Dapr等项目是相同的，但是Dapr等项目走的非常靠前，其逻辑依赖于独立部署的dapr-sidecar来实现。
63+
[Future plans for dapr api](https://github.com/dapr/dapr/issues/2817)
3164

32-
这就要求从最底层的基础设施层进行支持，但很多时候，我们并不能一步到位的切换到sidecar的模式。
65+
### Capa features
3366

34-
故Capa将sidecar中的逻辑移植到SDK中，应用无需依赖sidecar，引入SDK即可。
67+
Capa (Java SDK) is an SDK solution that implements Mecha architecture for Java applications. It currently supports features in the following areas:
3568

36-
未来肯定是要发展向Dapr这种模式，但是在过渡期，Capa这种模式将一直存在。
69+
+ Service Invocation (RPC)
70+
+ Configuration Centor (Configuration)
71+
+ Publish/Subscribe (Pub/Sub)
72+
+ State Management (State)
73+
+ Application Log/Metrics/Traces (Telemetry)
74+
+ Database (SQL) -alpha
75+
+ Schedule (Schedule) -alpha
76+
+ ...
3777

38-
**参考资料：** https://github.com/dapr/dapr/issues/2817
78+
## Design
3979

40-
## API Design
80+
### Capa design
4181

42-
API设计和社区保持同步，请参考Dapr/Layotto等开源项目的设计。
82+
Design idea: **Standard API + pluggable and replaceable SDK components** mode
4383

44-
目前API定义在: [cloud-runtimes](https://github.com/reactivegroup/cloud-runtimes-jvm) 中
84+
In different distributed middleware fields, Capa provides a unified standard programming API without relying on specific middleware APIs. Therefore, the application does not need to rely on any specific middleware API when programming with Capa, but only needs to rely on Capa's standard programming API.
4585

46-
#### SDK层次设计
86+
When deployed to different target environments, Capa will load different implementation classes of the standard API into the application. When calling a unified programming API, the underlying runtime will be adapted to different specific middleware SDK implementations.
87+
88+
The middleware team needs to develop the implementation classes of the standard API in the target environment for different target environments; and the application code can have a "write once, run anywhere" development experience.
89+
90+
### SDK design
91+
92+
The Capa module is divided into the following parts:
4793

48-
module划分主要为以下几个部分：
4994
* sdk
5095
* sdk-component
5196
* sdk-spi
5297
* sdk-spi-demo/...
5398

5499
![capa-design](./docs/capa-design/capa-layer.PNG)
55100

56-
应用程序编程时只需要依赖sdk即可，并使用SDK模块中定义的统一编程API。
101+
Application programming only needs to rely on the SDK, and use the unified programming API defined in the SDK module.
57102

58-
在运行前，会将具体的SPI实现包引入进去，作为统一编程API的具体实现。
103+
Before running, the specific SPI implementation package will be introduced as a specific implementation of the unified programming API.
59104

60-
#### 举例：[RPC API design]()
105+
## Usage
61106

62-
## Getting Started
107+
### Getting Started
63108

64109
#### Importing Capa's Java SDK
65110

66111
For a Maven project, add the following to your pom.xml file:
67112

68113
```xml
114+
69115
<project>
70-
...
71-
<dependencies>
72116
...
73-
<!-- Capa's core SDK with all features. -->
74-
<dependency>
75-
<groupId>group.rxcloud</groupId>
76-
<artifactId>capa-sdk</artifactId>
77-
<version>1.0.4.RELEASE</version>
78-
</dependency>
117+
<dependencies>
118+
...
119+
<!-- Capa's core SDK with all features. -->
120+
<dependency>
121+
<groupId>group.rxcloud</groupId>
122+
<artifactId>capa-sdk</artifactId>
123+
<version>1.0.6.RELEASE</version>
124+
</dependency>
125+
...
126+
</dependencies>
79127
...
80-
</dependencies>
81-
...
82128
</project>
83129
```
84130

85131
Sample implementation library:
86132

87133
```xml
134+
88135
<project>
89-
...
90-
<dependencies>
91136
...
92-
<!-- Capa's core SDK with all features. -->
93-
<dependency>
94-
<groupId>group.rxcloud</groupId>
95-
<artifactId>capa-sdk-spi-demo</artifactId>
96-
<version>1.0.4.RELEASE</version>
97-
</dependency>
137+
<dependencies>
138+
...
139+
<!-- Capa's core SDK with all features. -->
140+
<dependency>
141+
<groupId>group.rxcloud</groupId>
142+
<artifactId>capa-sdk-spi-demo</artifactId>
143+
<version>1.0.6.RELEASE</version>
144+
</dependency>
145+
...
146+
</dependencies>
98147
...
99-
</dependencies>
100-
...
101148
</project>
102149
```
103150

104-
#### Running the examples
151+
### Running the examples
105152

106153
Try the following examples to learn more about Capa's Java SDK:
107154

108155
* [capa-demo](https://github.com/reactivegroup/capa/tree/master/sdk-spi-demo)
109156
* [capa-aws](https://github.com/reactivegroup/capa-aws)
110157
* [capa-alibaba](https://github.com/reactivegroup/capa-alibaba)
111158

159+
### Low retrofit cost migration
160+
161+
If you want to use the native Capa API, your legacy system needs to face a large refactoring workload.
162+
163+
In order to make the migration low-cost, we can reuse the middleware API currently used.
164+
165+
By developing an adaptation layer project (providing the same annotation/interface call method), the implementation of the original middleware API is changed to Capa API.
166+
167+
In this way, the application only needs to change a few code (such as changing the path name of the annotation/interface) to migrate to the Capa architecture.
168+
169+
For discussion of this issue, please see:
170+
171+
[Java sdk design 调研：能否复用业界已有的事实标准](https://github.com/mosn/layotto/issues/206)
172+
173+
[Capa API adapted to spring annotation.](https://github.com/reactivegroup/sigs/issues/16)
174+
175+
[遗留中间件SDK无感迁移到Capa.](https://github.com/reactivegroup/sigs/issues/18)
176+
177+
## Develop
178+
112179
#### Reactor API
113180

114-
The Java SDK for Capa is built using [Project Reactor](https://projectreactor.io/). It provides an asynchronous API for Java. When consuming a result is consumed synchronously, as in the examples referenced above, the `block()` method is used.
181+
Taking into account the asynchronous call mode and the use of non-blocking IO, we provide the Reactor programming model natively. You can also use the synchronous call function through its `block()` method.
115182

116-
The code below does not make any API call, it simply returns the [Mono](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html) publisher object. Nothing happens until the application subscribes or blocks on the result:
183+
The Java SDK for Capa is built using [Project Reactor](https://projectreactor.io/). It provides an asynchronous API for
184+
Java. When consuming a result is consumed synchronously, as in the examples referenced above, the `block()` method is
185+
used.
186+
187+
The code below does not make any API call, it simply returns
188+
the [Mono](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html) publisher object. Nothing
189+
happens until the application subscribes or blocks on the result:
117190

118191
```java
119-
Mono<String> result = capaRpcClient.invokeMethod(SERVICE_APP_ID, "say", "hello", HttpExtension.POST, null, TypeRef.STRING);
192+
Mono<String> result=capaRpcClient.invokeMethod(SERVICE_APP_ID,"say","hello",HttpExtension.POST,null,TypeRef.STRING);
120193
```
121194

122-
To start execution and receive the result object synchronously, use `block()`. The code below shows how to execute the call and consume an empty response:
195+
To start execution and receive the result object synchronously, use `block()`. The code below shows how to execute the
196+
call and consume an empty response:
123197

124198
```java
125-
Mono<String> result = capaRpcClient.invokeMethod(SERVICE_APP_ID, "say", "hello", HttpExtension.POST, null, TypeRef.STRING);
126-
String response = result.block();
199+
Mono<String> result=capaRpcClient.invokeMethod(SERVICE_APP_ID,"say","hello",HttpExtension.POST,null,TypeRef.STRING);
200+
String response=result.block();
127201
```
128202

129203
#### Exception handling
130204

131-
Most exceptions thrown from the SDK are instances of `CapaException`. `CapaException` extends from `RuntimeException`, making it compatible with Project Reactor.
205+
Most exceptions thrown from the SDK are instances of `CapaException`. `CapaException` extends from `RuntimeException`,
206+
making it compatible with Project Reactor.
207+
208+
## Future
209+
210+
### Multi-Runtime
211+
212+
[Multi-Runtime 2022：待解决的问题](https://zhuanlan.zhihu.com/p/435012312?utm_source=wechat_session&utm_medium=social&utm_oi=618742049890111488&utm_content=group2_article&utm_campaign=shareopn)

0 commit comments

Comments
 (0)