This is an automated email from the ASF dual-hosted git repository.
liujun pushed a commit to branch dubbo3
in repository https://gitbox.apache.org/repos/asf/dubbo-js.git
The following commit(s) were added to refs/heads/dubbo3 by this push:
new deef042 update project and samples readme
new 6ba8418 Merge pull request #347 from chickenlj/dubbo3-README
deef042 is described below
commit deef04297d9a7f2cb7bb9ae9ebc71a6e70ce5e36
Author: chickenlj <[email protected]>
AuthorDate: Thu Aug 10 19:53:48 2023 +0800
update project and samples readme
---
.asf.yaml | 5 +-
README.md | 90 ++++++++++++++++++++----------------
example/dubbo-node-example/README.md | 36 +++------------
example/dubbo-web-example/README.md | 79 ++++++++++++++++++-------------
4 files changed, 107 insertions(+), 103 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
index 7c28b22..f4467e2 100644
--- a/.asf.yaml
+++ b/.asf.yaml
@@ -25,11 +25,14 @@ notifications:
github:
homepage: https://dubbo.apache.org/
- description: "The Node.js implementation of Apache Dubbo. An RPC and
microservice framework."
+ description: "The Typescript implementation of Apache Dubbo. An RPC and
microservice framework for Node.js and Web development."
labels:
- rpc
- nodejs
+ - web
- javascript
+ - typescript
+ - http
- http2
- microservices
- service-mesh
diff --git a/README.md b/README.md
index 9430343..6b26698 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,81 @@
-# Apache Dubbo-js
+# Apache Dubbo for ECMAScript
+
+[](https://github.com/apache/dubbo-js/blob/dubbo3/.github/workflows/node.js.yml)
-## Dubbo 介绍
+Apache Dubbo is an easy-to-use Web and RPC framework that provides different
+language implementations([Java](https://github.com/apache/dubbo),
[Go](https://github.com/apache/dubbo-go),
[Rust](https://github.com/apache/dubbo-rust), Node.js, Javascript) for
communication, service discovery, traffic management,
+observability, security, tools, and best practices for building
enterprise-ready microservices.
-- Apache Dubbo 是一款 RPC 服务开发框架，用于解决微服务架构下的服务治理与通信问题，官方提供了
Java、Golang，TypeScript，Rust 等多语言 SDK 实现。使用 Dubbo 开发的微服务原生具备相互之间的远程地址发现与通信能力， 利用
Dubbo 提供的丰富服务治理特性，可以实现诸如服务发现、负载均衡、流量调度等服务治理诉求。Dubbo
被设计为高度可扩展，用户可以方便的实现流量拦截、选址的各种定制逻辑。
+Dubbo-js is the TypeScript implementation of [Dubbo triple protocol (a fully
gRPC compatible and http friendly
protocol)](https://dubbo.apache.org/zh-cn/overview/reference/protocols/triple-spec/),
which can be used for Node.js and web application development. With dubbo-js,
you can easily build applications working on browser and frontend that can
communicate with backend services through http-based protocol.
-- 在云原生时代，Dubbo 相继衍生出了 Dubbo3、Proxyless Mesh
等架构与解决方案，在易用性、超大规模微服务实践、云原生基础设施适配、安全性等几大方向上进行了全面升级。
+* [Node.js
Documentation](https://dubbo.apache.org/zh-cn/overview/mannual/nodejs-sdk/)
+* [Web Documentation](https://dubbo.apache.org/zh-cn/overview/mannual/web-sdk/)
-## Dubbo-js 介绍
+## Get Started
+The following two demos will guide you on how to create Node.js backend and
web applications using dubbo-js.
-- 随着微服务场景的大范围应用，多语言场景越来越普遍，开发人员更愿意使用更适合的语言，来实现一个复杂系统的不同模块。所以 Dubbo 提供几乎所有主流语言的
SDK 实现，定义了一套统一的微服务开发范式。Dubbo 与每种语言体系的主流应用开发框架做了适配，总体编程方式、配置符合大多数开发者已有编程习惯。
+You can call backend Dubbo services with type-safe APIs:
-- Dubbo-js 与 JavaScript 生态系统集成，因为 Node.js 的轻量和高性能特点使其非常适合微服务架构，Web
端也需要直接向微服务发送请求。
+```typescript
+const resp = await client.say({sentence: "Hello, Dubbo."});
+console.log(resp);
+```
-- Dubbo-js 语言实现，架起 Node.js，Web 和 Java，Golang，Rust 等其他语言之间的桥梁，与 gRPC/Dubbo
生态互联互通，带领 Java 生态享受云原生时代的技术红利。
+Or, you can curl them if you want:
-- Dubbo-js 包含对 Node.js，以及 Web 端的实现，并针对两者的不同运行环境，进行了相对应的优化。除此之外，Dubbo 对
express，fastify，next 等中间件进行集成，方便用户更方便的去用 Node.js 搭建一个 Dubbo 分布式服务框架。
+```shell
+curl \
+ --header 'Content-Type: application/json' \
+ --data '{"sentence": "Hello World"}' \
+ http://localhost:8080/apache.dubbo.demo.example.v1.ExampleService/Say
+```
-## RPC 调用
+### Get started on the web
+Follow this [guide]() to learn how to develop web applications that can access
backend Dubbo services and running on browser.
-- 完全支持 gRPC 协议，以及支持 [Triple
协议](https://cn.dubbo.apache.org/zh-cn/overview/reference/protocols/triple-spec/)
进行通信
+We support all modern web browsers that implement the widely available fetch
API and the Encoding API.
-- Triple 协议是 Dubbo3 生态主推的协议，是基于 gRPC 的扩展协议，底层为 HTTP2，可与 gRPC 服务互通。**相当于在 gRPC
可靠的传输基础上，增加了 Dubbo 的服务治理能力。**
+### Get started on Node.js
-## 序列化
+Follow this [guide](./example/dubbo-node-example/) here to learn how to
develop and spin up a backend Dubbo service in Node.js, and call it from cURL,
the web browser, or a Dubbo client in your terminal.
-- 借助 protocol buffer 实现序列化以及反序列化
+In addition, Dubbo integrates middlewares such as express, fastify, and next,
making it easier for users to build a Dubbo distributed service framework using
Node.js.
-## 服务治理
+## Service Governance features
+Besides rpc protocol, we plan to provide dubbo-js rich service governance
features so it can work seamlessly with other microservice architecture.
-
+The features lsited below are still under development, we will update each
feature's status once ready.
-- **注册中心**:
+- :construction: **Service Discovery**:
- 支持 Nacos（阿里开源） 、Zookeeper、ETCD、Consul、Polaris-mesh（腾讯开源）
等服务注册中间件，并拥有可扩展能力。我们也会根据用户使用情况，进一步扩展出用户需要的实现。
+ Nacos, Zookeeper, Kubernetes, etc.
-- **配置中心**:
+- :construction: **Load Balance**:
- 开发者可以使用 Nacos、Zookeeper 进行框架/用户的配置的发布和拉取。
+ Random, RoundRobin, LeastActive, ConsistentHash, etc.
-- **负载均衡策略**:
+- :construction: **Traffic Routing**:
+ Traffic split, Circuit breaking, Canary release, etc.
- 柔性服务, Random, RoundRobin, LeastActive, ConsistentHash 等
+- :construction: **Filter**:
+ Token, AccessLog, Rate limiting, etc.
-- **过滤器**:
- Echo, Hystrix, Token, AccessLog, TpsLimiter, ExecuteLimit, Generic,
Auth/Sign, Metrics, Tracing, Active, Seata, Sentinel 等
-
-- **泛化调用**:
-
-- **监控**:
+- :construction: **Metrics**:
Prometheus
-- **链路追踪**:
+- :construction: **Tracing**:
Jaeger, Zipkin
-- **路由器**:
- Dubbo3 Router
-
-## 快速开始
-
-- 请访问 [Node
DOCS](https://cn.dubbo.apache.org/zh-cn/overview/quickstart/Node.js/) 和 [Web
DOCS](https://cn.dubbo.apache.org/zh-cn/overview/quickstart/Web/)
来了解如何简单的搭建一个基于 Node.js 的服务器，以及如何用 Node.js 或 Web 向服务器发送请求
+## How to contribute
-## 如何贡献
+Please check [CONTRIBUTING](./CONTRIBUTING.md) for how to contribute to this
project.
-- 请访问 [CONTRIBUTING](./CONTRIBUTING.md) 来了解如何提交更新以及贡献工作流。
+## Connect us
-## 联系
+Search Dingding group number and join us: 27690019068
-- [钉钉群](https://www.dingtalk.com/): 23331795
+## Credit
-## 许可证
+This project is based on
[bufbuild/connect-es](https://github.com/bufbuild/connect-es), an open-source
project released under Apache License v2. Comparing to connect-es, dubbo-js
removed the unused grpc-web and connect protocol, added support for Dubbo
protocol, no-idl programming api and many service governance features.
-- Apache Dubbo-go 使用 Apache 许可证 2.0 版本，请参阅 LICENSE 文件了解更多。
+We have a announcement in our LICENSE file and keep all license headers of
files come from connect-es unchanged.
\ No newline at end of file
diff --git a/example/dubbo-node-example/README.md
b/example/dubbo-node-example/README.md
index 2a76c09..6a5b9d4 100644
--- a/example/dubbo-node-example/README.md
+++ b/example/dubbo-node-example/README.md
@@ -1,31 +1,15 @@
-# Node RPC
+# 使用 Node.js 开发后端服务
-[前置条件](#precondition)
+基于 Dubbo 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2
上。Dubbo Node.js SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 API 来发布或调用这些服务。
-[定义服务](#defineService)
-
-[生成代码](#generateCode)
-
-[实现服务](#implementService)
-
-[启动 Server](#startServer)
-
-[访问服务](#accessService)
-
-[更多内容](#moreContent)
-
-[框架侧待改造](#transform)
-
-基于 Dubbo 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2
上。Dubbo TypeScript SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 APl 来发布或调用这些服务。
-
-本示例演示了基于 Triple 协议的 RPC 通信模式，示例使用 Protocol Buffer 定义 RPC
服务，并演示了代码生成、服务发布和服务访问等过程。本示例完整代码请请参见
[xxx](https://aliyuque.antfin.com/__workers/ken.lj/qt1o6i/pw02wty1pin10eia/a)
+本示例演示了基于 Triple 协议的 RPC 通信模式，示例使用 Protocol Buffer 定义 RPC
服务，并演示了代码生成、服务发布和服务访问等过程。
## <span id="precondition">前置条件</span>
-因为使用 Protocol Buffer 的原因，我们首先需要安装相关的代码生成工具，这包括
`@bufbuild/protoc-gen-es`、`@bufbuild/protobuf`、`apache-protoc-gen-dubbo-es`、`apache-dubbo`。
+因为使用 Protocol Buffer 的原因，我们首先需要安装相关的代码生成工具，这包括
`@bufbuild/protoc-gen-es`、`@bufbuild/protobuf`、`protoc-gen-apache-dubbo-es`、`apache-dubbo`。
```Shell
-npm install @bufbuild/protoc-gen-es @bufbuild/protobuf
apache-protoc-gen-dubbo-es apache-dubbo
+npm install @bufbuild/protoc-gen-es @bufbuild/protobuf
protoc-gen-apache-dubbo-es apache-dubbo
```
## <span id="defineService">定义服务</span>
@@ -190,12 +174,6 @@ void main();
npx tsx client.ts
```
-## <span id="moreContent">更多内容</span>
-
-- 使用 Dubbo JS 开发微服务
-- 更多 Dubbo JS 特性
-
-## <span id="transform">框架侧待改造</span>
+## 其他
-- 协议细节还需商讨并修改
-- 考虑后续整体生态，增强服务治理能力，添加日志等
+参考[开发运行在浏览器上的 web 应用](../dubbo-web-example/README.md)，了解如何开发能访问 Dubbo
后端服务的浏览器页面。
\ No newline at end of file
diff --git a/example/dubbo-web-example/README.md
b/example/dubbo-web-example/README.md
index e05910c..8d6a3ee 100644
--- a/example/dubbo-web-example/README.md
+++ b/example/dubbo-web-example/README.md
@@ -1,26 +1,14 @@
-# Web RPC
-
-[前置条件](#precondition)
-
-[定义服务](#defineService)
-
-[生成代码](#generateCode)
-
-[启动 Server](#startServer)
-
-[创建 App](#createApp)
-
-[更多内容](#moreContent)
-
-[框架侧待改造](#transform)
+# 浏览器端的 Web 应用示例
基于 Dubbo 定义的 Triple 协议，你可以轻松编写浏览器、gRPC 兼容的 RPC 服务，并让这些服务同时运行在 HTTP/1 和 HTTP/2
上。Dubbo TypeScript SDK 支持使用 IDL 或编程语言特有的方式定义服务，并提供一套轻量的 APl 来发布或调用这些服务。
-本示例演示了基于 Triple 协议的 RPC 通信模式，示例使用 Protocol Buffer 定义 RPC
服务，并演示了代码生成、服务发布和服务访问等过程。本示例完整代码请请参见
[xxx](https://aliyuque.antfin.com/__workers/ken.lj/qt1o6i/pw02wty1pin10eia/a)
+本示例演示了如何使用 dubbo-js 开发运行在浏览器上的 web 应用程序，web 页面将调用 dubbo node.js
开发的后端服务并生成页面内容。本示例演示基于 IDL 和非 IDL 两种编码模式。
-## <span id="precondition">前置条件</span>
+## IDL 模式
-首先，我们将使用 Vite 配置前端。我们使用 Vite 是为了创建一个快速的开发服务器，它内置了我们稍后需要的所有功能支持
+### <span id="precondition">前置条件</span>
+
+首先，我们将使用 Vite 来生成我们的前端项目模板，它内置了我们稍后需要的所有功能支持。
```Shell
npm create vite@latest -- dubbo-web-example --template react-ts
@@ -28,13 +16,13 @@ cd dubbo-web-example
npm install
```
-因为使用 Protocol Buffer 的原因，我们首先需要安装相关的代码生成工具，这包括
`@bufbuild/protoc-gen-es`、`@bufbuild/protobuf`、`apache-protoc-gen-dubbo-es`、`apache-dubbo`。
+因为使用 Protocol Buffer 的原因，我们首先需要安装相关的代码生成工具，这包括
`@bufbuild/protoc-gen-es`、`@bufbuild/protobuf`、`protoc-gen-apache-dubbo-es`、`apache-dubbo`。
```Shell
-npm install @bufbuild/protoc-gen-es @bufbuild/protobuf
apache-protoc-gen-dubbo-es apache-dubbo
+npm install @bufbuild/protoc-gen-es @bufbuild/protobuf
protoc-gen-apache-dubbo-es apache-dubbo
```
-## <span id="defineService">定义服务</span>
+### <span id="defineService">使用 Proto 定义服务</span>
现在，使用 Protocol Buffer (IDL) 来定义一个 Dubbo 服务。
@@ -68,13 +56,13 @@ service ExampleService {
## <span id="generateCode">生成代码</span>
-创建 gen 目录，做为生成文件放置的目标目录
+创建 gen 目录，作为生成文件放置的目标目录
```Shell
mkdir -p src/util/gen
```
-运行以下命令，在 gen 目录下生成代码文件
+运行以下命令，利用 `protoc-gen-es`、`protoc-gen-apache-dubbo-es` 等插件在 gen 目录下生成代码文件
```Shell
PATH=$PATH:$(pwd)/node_modules/.bin \
@@ -187,9 +175,9 @@ npm run dev
## <span id="startServer">启动 Server</span>
-接下来我们需要启动 Server
-这里我们采用 Dubbo 服务嵌入的 Node.js 服务器，可以根据 Node RPC 文档中的步骤，配合 Fastify 启动 Server
-不过需要注意，我们额外需要 @fastify/cors，来解决前端请求的跨域问题
+接下来我们需要启动 Server，这里我们采用 Dubbo 服务嵌入的 Node.js 服务器，具体可参考 [Node.js 开发 Dubbo
后端服务](../dubbo-node-example/README.md)中的操作步骤。
+
+不过需要注意，我们额外需要修改 Node.js 示例：引入 @fastify/cors 来解决前端请求的跨域问题
```Shell
npm install @fastify/cors
@@ -221,12 +209,39 @@ void main();
npx tsx server.ts
```
-## <span id="moreContent">更多内容</span>
+## 无 IDL 模式
+
+同样需要先安装 `apache-dubbo`、`apache-dubbo-web`
+
+```shell
+npm install apache-dubbo apache-dubbo-web
+```
+
+现在就可以一个启动一个客户端，并发起调用了。App.tsx 中的代码与 IDL 模式基本一致，区别点在于以下内容：
-- 使用 Dubbo JS 开发微服务
-- 更多 Dubbo JS 特性
+```typescript
+// ...
+// set backend server to connect
+const transport = createConnectTransport({
+ baseUrl: "http://localhost:8080";,
+});
+// init client
+const client = createPromiseClient(transport);
-## <span id="transform">框架侧待改造</span>
+function App() {
+ // ...
+ // call remote Dubbo service
+ const response = await client.call(
+ "apache.dubbo.demo.example.v1.ExampleService",
+ "say",
+ {
+ sentence: inputValue,
+ });
+}
+```
+
+执行以下命令，即可得到样例页面
-- 协议细节还需商讨并修改
-- 考虑后续整体生态，增强服务治理能力，添加日志等
+```Shell
+npm run dev
+```
\ No newline at end of file
