Conjure实战：从零搭建前后端分离的RPC服务

上一篇简单介绍了 Conjure，感受了它使用 YAML模型和接口 生成代码的简单和高效。这篇基于 https://github.com/palantir/conjure-java-example 写一个完整BS的例子，展示自建服务如何用 Conjure 来简化提升。

官方提供的例子 conjure-java-example 是基于他们的体系（或者说生态）来构建的。如果要在自己的项目中使用，我们需要剥离出一个最小化的运行环境。

本文中用的工具以及版本：

* Java 11
* Gradle 8
* Node 20（windows用于Conjure生成代码，wsl用于编写React）

内容分为三块：1、搭建基本框架，2、基础框架运行，3、运行Conjure。可以结合需要跳转到对应的部分。

# 1、搭建基本框架

先把Conjure、SpringBoot以及React的基本框架搭建起来。使用AI来创建SpringBoot和React工程：

# Conjure

首先创建gradle工程，把Conjure结构创建出来。

Prompt: 创建一个gradle的名字为hello-conjure-2的工程。新增子工程hello-api，在hello-api中添加src/main/conjure/hello.yml的文件。gradle配置保持最简单，只配置必须的配置。

这里先不修改。先把框架搭起来，后面再统一完善。

# SpringBoot

Prompt： 创建一个名为hello-server工程，使用jdk-11的springboot工程。sprintboot添加starter web，starter jersey的依赖。junit5依赖指定具体版本。使用本地的gradle，并且不需要settings.gradle文件。

# React

Prompt: 创建一个名称为hello-web的react web工程，使用语言typescript，使用框架react的。

完成后，把 hello-server 添加到 settings.gradle。目录结构如下：

# 2、跑起来：运行基础框架

# Conjure

根据上一篇文章中的配置修改Gradle：

settings.gradle

rootProject.name = 'hello-conjure-2' include'hello-api' include'hello-api:hello-api-objects' include'hello-api:hello-api-jersey' include'hello-api:hello-api-typescript' include'hello-server'

build.gradle

buildscript {     repositories {         mavenCentral()     }     dependencies {         classpath'com.palantir.gradle.conjure:gradle-conjure:5.10.0'     } } allprojects {     repositories {         mavenCentral()     } } apply plugin: 'com.palantir.conjure' // 需要定义在rootProject, 指定依赖的版本号 configurations {     conjureCompiler     conjureJava     conjureTypeScript } dependencies {     conjureCompiler 'com.palantir.conjure:conjure:4.16.1'     conjureJava 'com.palantir.conjure.java:conjure-java:6.5.0'     conjureTypeScript 'com.palantir.conjure.typescript:conjure-typescript:5.4.0' } subprojects {     apply plugin: 'java-library'     apply plugin: 'com.palantir.conjure'          sourceCompatibility = 11     targetCompatibility = 11          compileJava { options.encoding = "UTF-8" }          conjure {         typescript { version = "0.0.1" }         java { useImmutableBytes = true }     }          dependencies {         implementation "com.palantir.conjure.java:conjure-lib:6.5.0"     } }

hello-api/build.gradle(空文件即可）

// 

# SpringBoot

依然使用AI给 SprintBoot 添加hello接口。Prompt： 增加/hello的rest controller。并生成对应的test单元测试，使用springboottest写测试用例

HelloController.java

package com.example.helloserver; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController {     @GetMapping("/hello")     public String hello() {         return "Hello, World!";     } }

HelloServerApplicationTests.java

package com.example.helloserver; import static org.assertj.core.api.Assertions.assertThat; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.web.client.TestRestTemplate; import org.springframework.boot.web.server.LocalServerPort; @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) class HelloServerApplicationTests {     @LocalServerPort     private int port;     @Autowired     private TestRestTemplate restTemplate;     @Test     void helloEndpointReturnsHelloWorld() {         String url ="http://localhost:" + port + "/hello";         String response = restTemplate.getForObject(url, String.class);         assertThat(response).isEqualTo("Hello, World!");     } }

运行完善后的 hello-server 的 build.gradle：

plugins {     id 'org.springframework.boot' version '2.5.4'     id 'io.spring.dependency-management' version '1.0.11.RELEASE'     id 'java' } dependencies {     implementation 'org.springframework.boot:spring-boot-starter-web'     implementation 'org.springframework.boot:spring-boot-starter-jersey'     testImplementation 'org.springframework.boot:spring-boot-starter-test'     testImplementation platform('org.junit:junit-bom:5.10.2')     testImplementation 'org.junit.jupiter:junit-jupiter'     testRuntimeOnly 'org.junit.platform:junit-platform-launcher' } test {     useJUnitPlatform() }

# React web

修改 package.json 下 React 版本：

  "dependencies":{     "conjure-client":"^2.15.0",     "hello-api":"link:../hello-api/hello-api-typescript/src/",     "react":"^17.0.2",     "react-dom":"^17.0.2",     "typescript":"^4.4.4" }, "devDependencies":{     "@types/react":"^17.0.2",     "@types/react-dom":"^17.0.2",     "react-scripts":"5.0.1" },

使用Nodejs 20，并安装好依赖。

winse@DESKTOP-H3OHF4N:hello-web$ nvm use 20 Now using node v20.19.4 (npm v10.8.2) winse@DESKTOP-H3OHF4N:hello-web$ yarn 

再使用AI给 example 增加加功能。选择example tsx，输入提示词Prompt：完善功能，实现列表和增加表单，以及删除。

运行起来后，整体的效果和目录结果：

# 3、运行Conjure

# Conjure 模型

直接使用 conjure-java-example 中的模型和接口。

hello-api/src/main/conjure/hello.yml

types:   definitions:     default-package:com.palantir.conjure.examples.recipe.api     objects:       Temperature:         fields:           degree:double           unit:TemperatureUnit       Ingredient:         alias:string       RecipeName:         alias:string       BakeStep:         fields:           temperature:Temperature           durationInSeconds:integer       RecipeStep:         union:           mix:set<Ingredient>           chop:Ingredient           bake:BakeStep       Recipe:         fields:           name:RecipeName           steps:list<RecipeStep>       TemperatureUnit:         values:           -FAHRENHEIT           -CELSIUS     errors:       RecipeNotFound:         namespace:Recipe         code:NOT_FOUND         safe-args:           name:RecipeName services: RecipeBookService:     name:RecipeBook     package:com.palantir.conjure.examples.recipe.api     base-path:/recipes     docs:|       APIs for retrieving recipes     endpoints:       createRecipe:         http:POST/         args:           createRecipeRequest:             param-type:body             type:Recipe       getRecipe:         http:GET/{name}         args:           name:RecipeName         returns:Recipe         docs:|           Retrieves a recipe for the given name.           @paramname                  Thenameoftherecipe       getAllRecipes:         http:GET/         returns:set<Recipe>       deleteRecipe:         http:DELETE/{name}         args:           name: RecipeName

确认下 build.gradle 要生成的语言，然后运行脚本生成代码：

set PATH=D:\node-v20.13.1-win-x64;E:\local\gradle-8.13\bin;C:\Java\jdk-11.0.12\bin;%PATH% gradle compileConjure

# SpringBoot

添加 Conjure 和 API 的依赖到server的build.gradle，修改如下：

plugins {     id 'org.springframework.boot' version '2.5.4'     id 'io.spring.dependency-management' version '1.0.11.RELEASE'     id 'java' } dependencies {     implementation 'org.springframework.boot:spring-boot-starter-web'     implementation 'org.springframework.boot:spring-boot-starter-jersey'     implementation 'com.palantir.conjure.java.runtime:conjure-java-jersey-server:6.16.0'     implementation 'com.palantir.conjure.java.runtime:conjure-java-jaxrs-client:6.16.0'     implementation 'org.mpierce.metrics.reservoir:hdrhistogram-metrics-reservoir:1.1.3'     api project(':hello-api:hello-api-objects')     api project(':hello-api:hello-api-jersey')     testImplementation 'org.springframework.boot:spring-boot-starter-test'     testImplementation platform('org.junit:junit-bom:5.10.2')     testImplementation 'org.junit.jupiter:junit-jupiter'     testRuntimeOnly 'org.junit.platform:junit-platform-launcher' } test {     useJUnitPlatform() }

然后实现 RecipeBookResource.java，添加 Spring 的注解 @Component 让这个资源能被扫描自动注册：

package com.example.helloserver.resource; import java.util.ArrayList; import java.util.List; import java.util.Set; import org.springframework.stereotype.Component; import com.palantir.conjure.examples.recipe.api.Recipe; import com.palantir.conjure.examples.recipe.api.RecipeBookService; import com.palantir.conjure.examples.recipe.api.RecipeName; @Component public class RecipeBookResource implements RecipeBookService {     List<Recipe> recipes = new ArrayList<>();     @Override     public void createRecipe(Recipe createRecipeRequest) {         System.err.println("createRecipeRequest: " + createRecipeRequest);         recipes.add(createRecipeRequest);     }     @Override     public Recipe getRecipe(RecipeName name) {         System.err.println("getRecipe: " + name);         return recipes.stream().filter(r -> r.getName().equals(name)).findFirst().get();     }     @Override     public Set<Recipe> getAllRecipes() {         return Set.copyOf(recipes);     }     @Override     public void deleteRecipe(RecipeName name) {         recipes.removeIf(r -> r.getName().equals(name));     } }

配置jersey服务，路径为 /api，同样添加spring的标注 @Component。使用package的方式配置自动扫描目录，同时添加conjure的特性feature。JerseyConfig.java：

package com.example.helloserver; import com.palantir.conjure.java.server.jersey.ConjureJerseyFeature; import org.glassfish.jersey.server.ResourceConfig; import org.springframework.stereotype.Component; import javax.ws.rs.ApplicationPath; @Component @ApplicationPath("/api")// 这是所有 JAX-RS 资源的根路径 public class JerseyConfig extends ResourceConfig {     public JerseyConfig() {         // 注册你的 JAX-RS 资源类         // register(HelloResource.class);         // 如果你的资源类都在某个包下，也可以通过包扫描来注册         packages("com.palantir.conjure.examples.recipe.api",                 "com.example.helloserver.resource",                 "com.example.helloserver.filter");         // 注册其他 JAX-RS 特性，例如 JSON 序列化/反序列化提供者         // Jersey 默认会处理 JSON，但有时你可能需要明确指定         // register(org.glassfish.jersey.jackson.JacksonFeature.class); // 如果需要Jackson支持         register(ConjureJerseyFeature.INSTANCE);     } }

运行HelloServerApplication，使用curl提交数据：

curl http://localhost:8080/api/recipes -H 'Content-Type: application/json' --data '{"name": "My recipe", "steps": []}'

使用java提交数据，HelloClient.java：

package com.example.helloclient; import java.nio.file.Paths; import com.palantir.conjure.examples.recipe.api.Recipe; import com.palantir.conjure.examples.recipe.api.RecipeBookService; import com.palantir.conjure.examples.recipe.api.RecipeName; import com.palantir.conjure.java.api.config.service.ServiceConfiguration; import com.palantir.conjure.java.api.config.service.UserAgent; import com.palantir.conjure.java.api.config.ssl.SslConfiguration; import com.palantir.conjure.java.client.config.ClientConfigurations; import com.palantir.conjure.java.client.jaxrs.JaxRsClient; import com.palantir.conjure.java.okhttp.NoOpHostEventsSink; public class HelloClient {     public static void main(String[] args) {         RecipeBookService recipeBookService = JaxRsClient.create(                 RecipeBookService.class,                 UserAgent.of(UserAgent.Agent.of("hello", "0.0.1")),                 NoOpHostEventsSink.INSTANCE,                 ClientConfigurations.of(ServiceConfiguration.builder()                         .addUris("http://localhost:8080/api/")                         .security(SslConfiguration.of(Paths.get("C:\\Java\\jdk-11.0.12\\lib\\security\\cacerts")))                         .build()));         recipeBookService.createRecipe(Recipe.builder().name(RecipeName.of("java client")).build());     }      }

# React web

下面具体介绍Web连服务器。

前面已经配置生成了typescript的代码 hello-api-typescript，下载依赖并编译它：

winse@DESKTOP-H3OHF4N:hello-conjure-2$ cd hello-api/hello-api-typescript/src/ winse@DESKTOP-H3OHF4N:src$ yarn  yarn install v1.22.22 info No lockfile found. [1/4] Resolving packages... [2/4] Fetching packages... [3/4] Linking dependencies... [4/4] Building fresh packages... success Saved lockfile. Done in 5.38s. winse@DESKTOP-H3OHF4N:src$ yarn build  yarn run v1.22.22 $ tsc Done in 0.65s.

在hello-web中引入 hello-api-typescript 和 conjure-client 。

使用软连接的方式添加本地库，这样改变不需要重新下载依赖，在api还不太稳定的情况下方便一点。

winse@DESKTOP-H3OHF4N:hello-web$ yarn add conjure-client winse@DESKTOP-H3OHF4N:hello-web$ yarn add link:../hello-api/hello-api-typescript/src/

添加依赖后 package.json 的内容如下：

  "dependencies":{     "conjure-client":"^2.15.0",     "hello-api":"link:../hello-api/hello-api-typescript/src/",     "react":"^17.0.2",     "react-dom":"^17.0.2",     "typescript":"^4.4.4"   },

新增上下文用来提供service，并在组件中调用服务提交数据和获取数据，实现如下：

ServiceContext.ts

import { FetchBridge, IHttpApiBridge } from "conjure-client"; import { IRecipeBookService, RecipeBookService } from "hello-api"; import React from "react"; export interface IServiceContextProps { recipeBookService: IRecipeBookService; } export class ServiceContextProps implements IServiceContextProps { private bridge: IHttpApiBridge;  constructor() {     this.bridge = new FetchBridge({       baseUrl: "http://127.0.0.1:8080/api",       userAgent: { productName: "hello", productVersion: "1.0.0" }     });   } public get recipeBookService(): IRecipeBookService {     return new RecipeBookService(this.bridge);   } } export const ServiceContext = React.createContext<ServiceContextProps | null>( null);

App.tsx

import React from 'react'; import ExampleComponent from './components/ExampleComponent'; import { ServiceContext, ServiceContextProps } from './context/ServiceContext'; const App: React.FC = () => {     return (         <ServiceContext.Providervalue={newServiceContextProps()}>         <div>             <h1>Welcome to Hello Web</h1>             <ExampleComponent />         </div>         </ServiceContext.Provider>     ); }; export default App;

ExampleComponent.tsx

import { IRecipe } from "hello-api"; import React, { useState, ChangeEvent, FormEvent, useContext } from "react"; import { ServiceContext } from "../context/ServiceContext"; const ExampleComponent: React.FC = () => {     const ctx = useContext(ServiceContext); // 获取上下文     const [items, setItems] = useState<IRecipe[]>([]);     const [title, setTitle] = useState("");     const loadItems = async () => {         const recipes = await ctx!.recipeBookService.getAllRecipes();         setItems(recipes);     };     const handleTitleChange = (e: ChangeEvent<HTMLInputElement>) => setTitle(e.target.value);     const handleAdd = async (e: FormEvent) => {         e.preventDefault();         if (!title.trim()) return;         await ctx?.recipeBookService.createRecipe({ name: title.trim(), steps: [] });         loadItems();         setTitle("");     };     const handleDelete = async (name: string) => {         await ctx?.recipeBookService.deleteRecipe(name);         loadItems();     };     return (         <div>             <h2>列表</h2>             <ul>                 {items.map((item) => (                     <li key={item.name}>                         <strong>{item.name}</strong>                         <button onClick={() => handleDelete(item.name)} style={{ marginLeft: 8 }}>                             删除                         </button>                     </li>                 ))}             </ul>             <h2>新增</h2>             <form onSubmit={handleAdd}>                 <input type="text" placeholder="标题" value={title} onChange={handleTitleChange} required />                 <button type="submit">添加</button>             </form>         </div>     ); }; export default ExampleComponent;

此时运行是报错的，服务器端口8080，前端页面是3000的。还需要处理下跨域的问题。添加CorsConfig.java：

package com.example.helloserver.filter; import java.io.IOException; import javax.ws.rs.container.ContainerRequestContext; import javax.ws.rs.container.ContainerResponseContext; import javax.ws.rs.container.ContainerResponseFilter; import javax.ws.rs.ext.Provider; import org.springframework.stereotype.Component; @Component @Provider public class CorsFilter implements ContainerResponseFilter {     @Override     public void filter(ContainerRequestContext req, ContainerResponseContext res) throws IOException {         res.getHeaders().add("Access-Control-Allow-Origin", "http://localhost:3000");         res.getHeaders().add("Access-Control-Allow-Credentials", "true");         res.getHeaders().add("Access-Control-Allow-Headers", "origin, content-type, accept, authorization, fetch-user-agent"); //!!!         res.getHeaders().add("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS, HEAD");     } }

修改JerseyConfig，把filter添加到扫描路径：

        packages("com.palantir.conjure.examples.recipe.api",                 "com.example.helloserver.resource",                 "com.example.helloserver.filter");

重启服务，用web再提交，这次算是完美。新增后，服务端的日志也输出，web的列表立即更新了。

# 思考

这个例子整了很久，涉及到前后端几个工程来来回回的切换。诚不欺我，第一步确实是比较艰难的。

环境搭建好以后，写好模型，然后生成代码，最后调用服务其实很简单的。完全不用费脑子去这些中间的胶水代码，你只需要关注模型，其他的 Conjure 都给你搞定了。

下一篇将对接一下高德的导航接口。