Skip to content

Commit

Permalink
📝 Update document website (#469)
Browse files Browse the repository at this point in the history
  • Loading branch information
@devkanro
devkanro authored Nov 8, 2022
1 parent ac6ef76 commit 9f98003
Show file tree
Hide file tree
Showing 2 changed files with 4 additions and 455 deletions.
205 changes: 4 additions & 201 deletions ReadMe.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,17 @@
</p>
<p>
<a href="https://github.com/grpc-ecosystem/awesome-grpc"><img alt="Awesome gRPC" src="https://raw.githubusercontent.com/sindresorhus/awesome/main/media/badge.svg" /></a>
<img src="https://img.shields.io/badge/jdk-11-green?logo=java" alt="JDK version"/>
<img src="https://img.shields.io/badge/gradle-%5E6.5-green?logo=gradle" alt="Gradle version"/>
<img src="https://img.shields.io/badge/jdk-17-green?logo=java" alt="JDK version"/>
<img src="https://img.shields.io/badge/gradle-%5E7.5-green?logo=gradle" alt="Gradle version"/>
<a href="https://mvnrepository.com/artifact/com.bybutter.sisyphus/sisyphus-bom"><img src="https://img.shields.io/maven-central/v/com.bybutter.sisyphus/sisyphus-bom" alt="Maven Central"/></a>
</p>
</h1>

Sisyphus is the way how we provide backend services. It integrates all tools and libraries needed for designing API
which follows the [Google API Improvement Proposals](https://aip.bybutter.com).

[中文文档](doc/zh-cn/ReadMe.md)
See the [documents](https://sisyphus.bybutter.com/) website for more details,
也包含[中文文档](https://sisyphus.bybutter.com/zh-Hans/)。

## We are rolling a huge boulder

Expand Down Expand Up @@ -75,201 +76,3 @@ in Gradle.
**And More** tools like [CEL(Common Expression Language)](https://github.com/google/cel-spec)
, [Filtering](https://aip.bybutter.com/160) and [Ordering](https://aip.bybutter.com/132#ordering) scripts will help you
to design APIs following Google AIP.

## Rolling with Sisyphus

Ready to rolling boulder with Sisyphus already? Hold on! We need to plan our route first.

1. **System requirement**

- Gradle 6.7+
- JDK 11+

2. **Configure Sisyphus with gradle.properties**

We
use [gradle.properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties)
to configure global settings of Sisyphus and all Sisyphus projects.

```properties
# [DEV,RT] Set developer name for developing environment.
sisyphus.developer=higan
# [DEV] Set development layer for replacing version of dependencies, could be 'API', 'PLATFORM', 'FRAMEWORK'.
sisyphus.layer=FRAMEWORK
# [RT] Set environment for configuration artifact.
sisyphus.environment=production

# Use 'sisyphus.repository.<name>.url' Register maven repository for Sisyphus usage.
# [DEV,RT] Url of repository named 'snapshot'.
sisyphus.repositories.snapshot.url=https://repo1.maven.org/maven2/
# [DEV,RT] Optional, user name of repository.
sisyphus.repositories.snapshot.username=
# [DEV,RT] Optional, password of repository.
sisyphus.repositories.snapshot.password=

# Repositories for different usage, there are 4 embedded repositories.
# 'local'(maven local), 'central'(maven central), 'portal'(gradle portal).

# [DEV,RT] Repositories for resolving dependencies, default value is 'local,central,portal'.
sisyphus.dependency.repositories=local,central,portal
# [DEV] Repositories for snapshot publishing, default value is 'snapshot'.
sisyphus.snapshot.repositories=snapshot
# [DEV] Repositories for release publishing, default value is 'release'.
sisyphus.release.repositories=release
# [DEV] Repositories for docker publishing.
sisyphus.docker.repositories=

# [RT] Configuration artifacts, it will be resolved in runtime.
sisyphus.config.artifacts=foo.bar:baz:1.0.0
```

> **[DEV]** for developing environment properties.
>
> **[RT]** for runtime environment properties.
`gradle.properties` are shared between Gradle and Spring. Sisyphus Project Plugin will load them and configure Gradle
automatically. Sisyphus Configuration Artifact will load them for Spring Framework.

3. **Write Protobuf schemas**

The next step is to design APIs, which means to create a schema project and to write `.proto` files in this project.

This is a sample schema project `build.gradle.kts` config.

```kotlin
plugins {
`java-library` // We build this project as a java library.
kotlin("jvm") version "1.3.72" // Use the kotlin plugin to compile .kt files
id("com.bybutter.sisyphus.project") version "1.2.2" // Use the sisyphus project management plugin.
id("com.bybutter.sisyphus.protobuf") version "1.2.2" // Use the sisyphus protobuf compiler plugin.
}

dependencies {
api("com.bybutter.sisyphus:sisyphus-grpc-coroutine:1.2.2") // Dependent on sisyphus grpc runtime.
/*proto("com.foo.bar:baz:1.0.0")*/ // Use 'proto' configuration to config jars need to compile proto.
/*protoApi("com.foo.bar:baz:1.0.0")*/ // Use 'protoApi' configuration to config needed jars in proto compiling.
// All dependencies in 'implementation' configuration will auto add to 'protoApi' configuration.
}
```

Now we can write `.proto` files in `src/main/proto` folder.

```protobuf
syntax = "proto3";
option java_multiple_files = true;
option java_package = "com.bybutter.sisyphus.examples.helloworld";
package sisyphus.examples.helloworld;
import "google/api/annotations.proto";
// The greeting api definition.
service GreetingApi {
// Sends a greeting
rpc Greet (GreetRequest) returns (GreetResponse) {
option (google.api.http) = {
post: "/v1:greet"
body: "*"
};
}
}
// The request message containing the user's name.
message GreetRequest {
string name = 1;
}
// The response message containing the greetings
message GreetResponse {
string message = 1;
}
```

> Additionally, `kotlin` and `java` classes are able to be added to schema project too. However, we do not recommend anything like this added excluding util or helper classes.
Use the `gradlew generateProtos` task to generate kotlin files from proto files.

4. **Implement API**

API schema is ready now. The next step is to implement this API schema. Create a service project and refer to the
schema project.

This is a sample service project `build.gradle.kts` config.

```kotlin
plugins {
`java-library`
kotlin("jvm") version "1.3.72"
id("com.bybutter.sisyphus.project") version "1.2.2"
}

dependencies {
api("com.bybutter.sisyphus.middleware:sisyphus-grpc-client:1.2.2") // Dependent on spring grpc runtime.
api(project("schema:example-schema")) // Dependent on schema project.
}
```

Create spring auto-config for service project.

```kotlin
@Configuration
@ComponentScan(basePackageClasses = [AutoConfig::class])
class AutoConfig
```

Register auto-config in `src/main/resources/META-INF/spring.factories`.

```properties
org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.bybutter.sisyphus.examples.helloworld.AutoConfig
```

Write the implementation by extend generated service classes.

```kotlin
@RpcServiceImpl
class GreetingApiImpl : GreetingApi() {
override suspend fun greet(input: GreetRequest): GreetResponse {
return GreetResponse {
message = "Hello ${input.name}!"
}
}
}
```

5. **Run the Application**

The service project is just a non-runnable library. We need to create an application project to run our service
projects.

This is a sample application project `build.gradle.kts` config.

```kotlin
plugins {
application
kotlin("jvm") version "1.3.72"
`kotlin-spring`
id("com.bybutter.sisyphus.project") version "1.2.2"
}

dependencies {
implementation("com.bybutter.sisyphus.starter:sisyphus-grpc-server-starter:1.2.2") // Dependent on spring grpc starter.
implementation("com.bybutter.sisyphus.starter:sisyphus-grpc-transcoding-starter:1.2.2") // [Optional] Enable the http-transcoding feature.
implementation("com.bybutter.sisyphus.starter:sisyphus-protobuf-type-server-starter:1.2.2") // [Optional] Enable the type server feature.
implementation(project("service:example-service")) // Dependent on service project.
}
```

We only need one function in the application project, the `main` function.

```kotlin
@SpringBootApplication
@EnableHttpToGrpcTranscoding
class MarcoApplication

fun main(args: Array<String>) {
SpringApplication.run(MarcoApplication::class.java, *args)
}
```

Use the `gradlew bootRun` task to run our application.
Loading

0 comments on commit 9f98003

Please sign in to comment.