jianyi-gronk commented on code in PR #394: URL: https://github.com/apache/dubbo-js/pull/394#discussion_r1583380343
########## docs/guide/dubboForNode/GettingStarted.md: ########## @@ -1 +1,295 @@ -# GettingStarted +# Getting started + +Dubbo-Node is a library for serving Dubbo, gRPC, and gRPC-Web compatible HTTP APIs using Node.js. It brings the Dubbo Protocol to Node with full TypeScript compatibility and support for all four types of remote procedure calls: unary and the three variations of streaming. + +This ten-minute walkthrough helps you create a small Dubbo service in Node.js. It demonstrates what you'll be writing by hand, what Connect generates for you, and how to call your new API. + + +# Prerequisites +We'll set up a project from scratch and then augment it to serve a new endpoint. + +- You'll need [Node.js](https://nodejs.org/en/download) installed - we recommend the most recent long-term support version (LTS). +- We'll use the package manager `npm`, but we are also compatible with `yarn` and `pnpm`. +- We'll also use [cURL](https://curl.se/). It's available from Homebrew and most Linux package managers. + + +# Project setup + +Let's initialize a project with TypeScript, and install some code generation tools: + +```shell +mkdir dubbo-example +cd dubbo-example +npm init -y +npm install typescript tsx +npx tsc --init +npm install @bufbuild/buf @bufbuild/protoc-gen-es @bufbuild/protobuf @apachedubbo/protoc-gen-apache-dubbo-es @apachedubbo/dubbo +``` + +# Define a service +First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of [ELIZA](https://en.wikipedia.org/wiki/ELIZA), the famous natural language processing program. + +```shell +mkdir -p proto && touch proto/eliza.proto +``` + +Open up the above file and add the following service definition: + +``` +syntax = "proto3"; + +package connectrpc.eliza.v1; + +message SayRequest { + string sentence = 1; +} + +message SayResponse { + string sentence = 1; +} + +service ElizaService { + rpc Say(SayRequest) returns (SayResponse) {} +} +``` + + +# Generate code + +We're going to generate our code using [Buf](https://www.npmjs.com/package/@bufbuild/buf), a modern replacement for Google's protobuf compiler. We installed Buf earlier, but we also need a configuration file to get going. (If you'd prefer, you can skip this section and use `protoc` instead — `protoc-gen-apache-dubbo-es` behaves like any other plugin.) + +First, tell Buf how to generate code with a `buf.gen.yaml` file: + +```yaml +version: v1 +plugins: + - plugin: es + opt: target=ts + out: gen + - plugin: dubbo-es + opt: target=ts + out: gen +``` + +With this file in place, you can generate code from the schema in the `proto` directory: + +```shell +npx buf generate proto +``` + +You should now see two generated TypeScript files: + +```markdown{3-5} +├── buf.gen.yaml +├── gen +│ ├── eliza_dubbo.ts +│ └── eliza_pb.ts +├── node_modules +├── package-lock.json +├── package.json +├── proto +│ └── eliza.proto +└── tsconfig.json +``` + +Next, we are going to use these files to implement our service. + + +# Implement the service + +We defined the `ElizaService` - now it's time to implement it, and register it with the `DubboRouter`. First, let's create a file where we can put the implementation: + +Create a new file `dubbo.ts` with the following contents: + +```tsx +import type { ConnectRouter } from "@apachedubbo/dubbo"; Review Comment: import { DubboRouter } from "@apachedubbo/dubbo"; ########## docs/guide/dubboForNode/ImplementingServices.md: ########## @@ -1 +1,234 @@ # ImplementingServices + +Dubbo handles HTTP routes and most plumbing for you, but implementing the actual business logic is still up to you. + +You always register your implementation on the `DubboRouter`. We recommend to create a file `connect.ts` with a registration function in your project: Review Comment: You always register your implementation on the `DubboRouter`. We recommend to create a file `dubbo.ts` with a registration function in your project: ########## docs/guide/dubboForNode/GettingStarted.md: ########## @@ -1 +1,295 @@ -# GettingStarted +# Getting started + +Dubbo-Node is a library for serving Dubbo, gRPC, and gRPC-Web compatible HTTP APIs using Node.js. It brings the Dubbo Protocol to Node with full TypeScript compatibility and support for all four types of remote procedure calls: unary and the three variations of streaming. + +This ten-minute walkthrough helps you create a small Dubbo service in Node.js. It demonstrates what you'll be writing by hand, what Connect generates for you, and how to call your new API. + + +# Prerequisites +We'll set up a project from scratch and then augment it to serve a new endpoint. + +- You'll need [Node.js](https://nodejs.org/en/download) installed - we recommend the most recent long-term support version (LTS). +- We'll use the package manager `npm`, but we are also compatible with `yarn` and `pnpm`. +- We'll also use [cURL](https://curl.se/). It's available from Homebrew and most Linux package managers. + + +# Project setup + +Let's initialize a project with TypeScript, and install some code generation tools: + +```shell +mkdir dubbo-example +cd dubbo-example +npm init -y +npm install typescript tsx +npx tsc --init +npm install @bufbuild/buf @bufbuild/protoc-gen-es @bufbuild/protobuf @apachedubbo/protoc-gen-apache-dubbo-es @apachedubbo/dubbo +``` + +# Define a service +First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of [ELIZA](https://en.wikipedia.org/wiki/ELIZA), the famous natural language processing program. + +```shell +mkdir -p proto && touch proto/eliza.proto +``` + +Open up the above file and add the following service definition: + +``` +syntax = "proto3"; + +package connectrpc.eliza.v1; Review Comment: package apache.dubbo.demo.example.v1; -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@dubbo.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: notifications-unsubscr...@dubbo.apache.org For additional commands, e-mail: notifications-h...@dubbo.apache.org
