案例篇：利用ProtoBuf文件，一键生成Java代码

作者: 小鱼爱记录 | 来源:发表于2018-12-02 21:00 被阅读144次

1.背景

在我们日常的开发中，前后端之间的接口联调很麻烦，经常出现后端加了字段，前端还不知道，所谓接口文档，经常和代码是不同步的。

好在现在有了grpc，它可以定义好ProtoBuf接口文件后，自动生成代码。原理就是RPC，在客户端生成一个远程服务的代理，可以像访问访问本地方法一样，访问远程方法。

但是，在客户端使用grpc的实践中，我们发现了grpc有几个弊端：

生成的实体类太大，很占内存，所以，我们最好只是用grpc的实体类来传输，但是在业务层，还是使用自己写的实体类更方便一点
自动生成的同步方法和异步方法，都不够好用，使用起来还是有一点点麻烦的
grpc生成的类都是final类，不便修改和继承
grpc生成的类没有实现Parcelable和Serializable接口，没法通过Intent传递，这在不同页面之间传递数据比较麻烦

为了解决grpc的弊端，我们最好在业务层自己封装一套实体类，grpc实体类只负责传输层，但是这又带来了一个新的问题：两套实体类之间互相转换的问题。

在我们的应用中，实体类的数量已经有接近800个，服务也有100多个。因为历史遗留问题，现在这些grpc的类还是广泛存在于业务层，迁移的话，非常麻烦。

经过一段时间的研究，我终于想到了一个方案：利用ProtoBuf接口文件，一键生成Java代码。

实现过程中，遇到了几个问题：

如何解析ProtoBuf文件？
因为我主要是玩Java的，所以还是想用Java代码来解析，但是在网上找了半天，好像都没有直接用Java解析ProtoBuf的方案。好在有一个替代方案，先将proto文件编译成desc文件，然后再来解析desc文件。
编译的话，就用Java调用一个cmd指令就好了
解析的话，就有不少坑了：
第1坑：List<int>里的int需要额外处理
第2坑：map字段需要额外处理
第3坑：message嵌套message需要额外处理
第4坑：类名重复问题，因为我之前都是直接生成到一个包里面的，这就难免重复了，所以protobuf里面定义的package字段也要用上，
其它的小坑就略过不提了~~~
如何生成Java代码？
这肯定要用到模板引擎来做代码自动生成了，这里我使用的是FreeMaker。因为之前没玩过它，在写ftl模板文件时，经常运行失败。后来才知道这个坑：FreeMaker的数据模型必须有get方法，哪怕你的字段是public的也必须要有。
了解了FreeMaker的语法之后，再来写的话，就方便多了，后来而遇到了一个坑：Class里面嵌套Class的问题。这种内部类该怎么生成？这就需要用到FreeMaker的宏来做递归了。

2. 案例

ProtoBuf定义

文件名：user.proto，这里仅是一个示例，其实这个定义文件也不规范，更好的定义规范，还需要实践探索，和自己的项目结合

syntax = "proto3";
package crm.usercenter;

message UserMessage {
    string name = 1;
    int32 id = 2;
    string message = 3;
    MessageType type=4;
}

message FindUserMessageByIdReq {
    int32 id = 1;
}

message Result {
    string msg = 4;
    int32 code = 5;
}

enum MessageType {
    SYSTEM = 0;
    CUSTOMER = 1;
    OTHER = 2;
}

service UserPublic {
    rpc FindUserMessageById (FindUserMessageByIdReq) returns (UserMessage);
    rpc AddUserMessage (UserMessage) returns (Result);
}

生成的实体类

这里就只贴一个message了，其它类似

package dest.bean.crm.usercenter;

import dest.bean.crm.usercenter.MessageType;

public class UserMessage {
    public String name;
    public int id;
    public String message;
    public MessageType type;

}

生成的枚举类

package dest.bean.crm.usercenter;

public enum MessageType {
    SYSTEM,
    CUSTOMER,
    OTHER,
}

生成的接口类

package dest.bean.crm.usercenter;

import dest.bean.crm.usercenter.FindUserMessageByIdReq;
import dest.bean.crm.usercenter.UserMessage;
import dest.bean.crm.usercenter.Result;

public interface UserPublic {

    UserMessage findUserMessageById(FindUserMessageByIdReq findUserMessageByIdReq);

    Result addUserMessage(UserMessage userMessage);

}

3. 异步封装

上面只是最基本的封装而已，其实用处不是很大，存在问题：

实体类自动生成，虽然减轻了一点工作量，不用自己再写那么多字段了，但是和Grpc生产的实体类之间的转换还是问题
生成的接口是同步的，但是我们在Android端用的话，肯定是要异步的接口的

下面，好戏开始上演了~~~

生成的异步接口

这里的异步接口，涉及到了我自己封装的网络层框架的几个接口了，
ResourceObserver是基于观察者模式实现的，类似于一个Rx的Disposable，用于取消网络请求，需要注册到ResourceSubject上。我们最好是将BaseActivity和BaseFragment都实现ResourceSubject接口，然后在退出Activity就可以自动取消网络请求了。

然后Consumer是我自己封装的函数式接口，之所以不用Rx和Java8的，主要是这种接口定义本来很简单，没必要过度依赖第三方，万一哪一天，我们不想用Rx了的话，用到这个接口的地方都得改，很蛋疼的。类似的我还封装了Mapper、Provider等几个函数式接口。

package dest.bean.crm.usercenter;

import com.ezbuy.functions.Consumer;
import com.ezbuy.web.ResourceObserver;

import dest.bean.crm.usercenter.FindUserMessageByIdReq;
import dest.bean.crm.usercenter.UserMessage;
import dest.bean.crm.usercenter.Result;

public interface UserPublicWebService {

    ResourceObserver findUserMessageById(FindUserMessageByIdReq findUserMessageByIdReq, Consumer<UserMessage> consumer);

    ResourceObserver addUserMessage(UserMessage userMessage, Consumer<Result> consumer);

}

生成异步接口的实现类

这里的异步接口的实现类是Rx的方式，返回的观察者是RxResourceObserver。但是实际上，我们完全可以将这里改成任何自己想要的方式。比如我们应用里面有GRPC和RPC两种方式，我们完全可以定义另外两种ResourceObserver。

package dest.bean.crm.usercenter;

import com.ezbuy.functions.Consumer;
import com.ezbuy.functions.Mapper;
import com.ezbuy.web.ResourceObserver;
import com.ezbuy.web.helper.RxExecuter;
import com.ezbuy.web.observer.RxResourceObserver;
import io.reactivex.disposables.Disposable;

public class UserPublicWebServiceImpl implements UserPublicWebService {

    @Override
    public ResourceObserver findUserMessageById(FindUserMessageByIdReq req, Consumer<UserMessage> consumer) {
        Disposable disposable = RxExecuter.execute(req, consumer, new Mapper<FindUserMessageByIdReq, UserMessage>() {
            @Override
            public UserMessage map(FindUserMessageByIdReq req) {
                UserOuterClass.UserMessage resp = UserPublicGrpc.newBlockingStub(null).findUserMessageById(new FindUserMessageByIdReqMapper().toGrpc(req));
                return new UserMessageMapper().fromGrpc(resp);
            }
        });
        return new RxResourceObserver(disposable);
    }
    
    @Override
    public ResourceObserver addUserMessage(UserMessage req, Consumer<Result> consumer) {
        Disposable disposable = RxExecuter.execute(req, consumer, new Mapper<UserMessage, Result>() {
            @Override
            public Result map(UserMessage req) {
                UserOuterClass.Result resp = UserPublicGrpc.newBlockingStub(null).addUserMessage(new UserMessageMapper().toGrpc(req));
                return new ResultMapper().fromGrpc(resp);
            }
        });
        return new RxResourceObserver(disposable);
    }
    
}

这是返回的RxResourceObserver，这里为了强行和Observer的官方接口保证一致，把cancel()命名为update()其实不好，以后再改回来吧。

package com.ezbuy.web.observer;

import com.ezbuy.web.ResourceObserver;
import com.ezbuy.web.ResourceSubject;
import io.reactivex.disposables.Disposable;

public class RxResourceObserver implements ResourceObserver {

    private Disposable disposable;

    public RxResourceObserver(Disposable disposable) {
        this.disposable = disposable;
    }

    @Override
    public void update() {
        System.out.println("请求反注册:" + disposable);
        if (isRelease()) {
            System.out.println("请求已取消,无须反注册");
        } else {
            System.out.println("请求未取消,执行反注册");
            disposable.dispose();
        }

    }

    @Override
    public void register(ResourceSubject manager) {
        System.out.println("请求注册:" + disposable);
        manager.attach(this);
    }

    @Override
    public boolean isRelease() {
        return disposable.isDisposed();
    }
}

这里是我们定义的其它的ResourceObserver，只以GRPC为例子吧，RPC的类似

package com.ezbuy.web.observer;

import com.daigou.model.grpc.GrpcRequest;
import com.ezbuy.web.ResourceSubject;

public class GrpcRequestObserver implements ResourceObserver {

    private GrpcRequest request;

    public GrpcRequestObserver(GrpcRequest request) {
        this.request = request;
    }

    @Override
    public void update() {
        request.cancel();
    }

    @Override
    public void register(ResourceSubject subject) {
        subject.attach(this);
    }

    @Override
    public boolean isRelease() {
        return request.isCanceled();
    }

}

生成的异步接口的测试类

为了方便测试接口通没通，我这里会自动根据protobuf生成测试类，每个接口方法都有

package dest.bean.crm.usercenter;

import com.ezbuy.functions.Consumer;
import com.ezbuy.web.ResourceSubject;
import com.ezbuy.web.ServiceFactory;
import com.ezbuy.web.observer.ResourceSubjectImpl;
import org.junit.After;
import org.junit.Before;
import org.junit.Test;

import java.util.concurrent.TimeUnit;

public class UserPublicWebServiceTest {

    @Before
    public void setUp() throws Exception {
        //注册服务,建议放在Application,UserPublicWebServiceImpl的实例会在需要时才初始化,并有弱引用的缓存,防止内存泄露
        ServiceFactory.registerService(UserPublicWebService.class, UserPublicWebServiceImpl.class);
    }

    @After
    public void tearDown() throws Exception {
        //反注册服务
        ServiceFactory.unRegisterService(UserPublicWebService.class);
    }

    @Test
    public void testFindUserMessageById() throws Exception {
        System.out.println("开始执行:testFindUserMessageById");
        long time = System.currentTimeMillis();
        //模拟Activity,我们最好在BaseActivity和BaseFragment实现此接口
        ResourceSubject activity = new ResourceSubjectImpl();
        //模拟网络请求
        FindUserMessageByIdReq req = new FindUserMessageByIdReq();
        ServiceFactory.getService(UserPublicWebService.class).findUserMessageById(req, new Consumer<UserMessage>() {
            @Override
            public void consume(UserMessage resp) {
                System.out.println("请求成功:" + resp);
            }
        }).register(activity);
        //其实不register也可以,但是那就不会自动取消了,回来时如果Activity退出了,Consumer的回调里面可能抛出空指针异常
        //模拟3秒之后,退出Activity
        TimeUnit.SECONDS.sleep(3);
        System.out.println("退出Activity");
        activity.notifyAllObservers();
        System.out.println("结束执行:testFindUserMessageById" + ",耗时:" + (System.currentTimeMillis() - time));
    }

    @Test
    public void testAddUserMessage() throws Exception {
        System.out.println("开始执行:testAddUserMessage");
        long time = System.currentTimeMillis();
        //模拟Activity,我们最好在BaseActivity和BaseFragment实现此接口
        ResourceSubject activity = new ResourceSubjectImpl();
        //模拟网络请求
        UserMessage req = new UserMessage();
        ServiceFactory.getService(UserPublicWebService.class).addUserMessage(req, new Consumer<Result>() {
            @Override
            public void consume(Result resp) {
                System.out.println("请求成功:" + resp);
            }
        }).register(activity);
        //其实不register也可以,但是那就不会自动取消了,回来时如果Activity退出了,Consumer的回调里面可能抛出空指针异常
        //模拟3秒之后,退出Activity
        TimeUnit.SECONDS.sleep(3);
        System.out.println("退出Activity");
        activity.notifyAllObservers();
        System.out.println("结束执行:testAddUserMessage" + ",耗时:" + (System.currentTimeMillis() - time));
    }

}

以testFindUserMessageById()方法为例，我们可以看看输出，基本是和预期一致的。

registerService:dest.bean.crm.usercenter.UserPublicWebService
开始执行:testFindUserMessageById
请求注册:io.reactivex.internal.operators.observable.ObservableMap$MapObserver@52af6cff
请求成功:dest.bean.crm.usercenter.UserMessage@37670c36
退出Activity
请求反注册:DISPOSED
请求已取消,无须反注册
结束执行:testFindUserMessageById,耗时:3365
unRegisterService:dest.bean.crm.usercenter.UserPublicWebService

test里面的ServiceFactory.getService(UserPublicWebService.class)是根据工厂模式，自己写的一个简单的服务工厂类，我们只需要将每一个接口类和实现类一一注册到这个工厂类就好了，使用它的好处就是，我可以很方便切换一个服务的具体实现方式，只需要改一下注册类就好了，具体使用的地方都不用动。

package com.ezbuy.web;


import com.ezbuy.web.error.ErrorConsumer;
import com.ezbuy.web.error.ErrorConsumerImpl;
import com.ezbuy.web.impl.CartServiceRxImpl;

import java.lang.ref.WeakReference;
import java.util.HashMap;
import java.util.Map;

/**
 * 服务管理类
 *
 * @author Yutianran
 */
public class ServiceFactory {

    //服务类 -> 实现类
    private static Map<Class<?>, Class<?>> router = new HashMap<>();

    //服务类 -> 实现对象的弱引用,资源不足时,GC会主动回收对象
    private static Map<Class<?>, WeakReference<Object>> implMap = new HashMap<>();

    //在这里静态注册所有服务
    static {
        router.put(CartService.class, CartServiceRxImpl.class);
        router.put(ErrorConsumer.class, ErrorConsumerImpl.class);
    }

    //在这里动态注册服务,不直接注册实现类的对象,是为了懒加载,在需要时再创建
    public static void registerService(Class<?> service, Class<?> impl) {
        System.out.println("registerService:"+service.getName());
        router.put(service, impl);
    }

    //反注册服务
    public static void unRegisterService(Class<?> service) {
        System.out.println("unRegisterService:"+service.getName());
        router.remove(service);
    }

    public static <T> T getService(Class<T> serverClass) {
        WeakReference<Object> reference = implMap.get(serverClass);
        Object obj = null;
        //缓存没有被清除掉
        if (reference != null) {
            obj = reference.get();
            if(obj!=null){
                return (T) obj;
            }
        }
        //缓存被清除掉了,或者是还没有创建缓存
        try {
            if (obj == null) {
                Class<?> implClass = router.get(serverClass);
                obj = implClass.newInstance();
                implMap.put(serverClass, new WeakReference<>(obj));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        return (T) obj;
    }

}

4. 兼容GRPC

上面其实故意漏了一个，就是具体是怎么将request变成response的呢，其实就在是异步接口实现类的map操作里面做的。

Disposable disposable = RxExecuter.execute(req, consumer, new Mapper<FindUserMessageByIdReq, UserMessage>() {
    @Override
    public UserMessage map(FindUserMessageByIdReq req) {
        UserOuterClass.UserMessage resp = UserPublicGrpc.newBlockingStub(null).findUserMessageById(new FindUserMessageByIdReqMapper().toGrpc(req));
        return new UserMessageMapper().fromGrpc(resp);
    }
});

这里涉及到了一个RxExecuter.execute，这个只是封装了Rx的subscribeOn和observeOn这些操作的工具类而已，等下会贴，现在我们的重点是：

UserOuterClass.UserMessage resp = UserPublicGrpc.newBlockingStub(null).findUserMessageById(new FindUserMessageByIdReqMapper().toGrpc(req));

这个才是test的时候实现request -> response的核心。

涉及到了两个类：UserOuterClass数据类、UserPublicGrpc请求执行类

生成的GRPC数据类-模拟

其实，这是只是模拟的GRPC数据类，真正的GRPC数据类是由protobuf-gradle-plugin插件自动生成的，但是因为我这个电脑没安装，就只好先用我自己生成的类来模拟了。

package dest.bean.crm.usercenter;

public class UserOuterClass {

    public static class UserMessage {
        public String name;

        public String getName() {
            return name;
        }
        public int id;

        public int getId() {
            return id;
        }
        public String message;

        public String getMessage() {
            return message;
        }
        public MessageType type;

        public MessageType getType() {
            return type;
        }

        private UserMessage(Builder builder) {
            name = builder.name;
            id = builder.id;
            message = builder.message;
            type = builder.type;
        }

        public static Builder newBuilder() {
            return new Builder();
        }

        public static final class Builder {
            private String name;
            private int id;
            private String message;
            private MessageType type;

            public Builder() {
            }

            public Builder setName(String name) {
                this.name = name;
                return this;
            }
            public Builder setId(int id) {
                this.id = id;
                return this;
            }
            public Builder setMessage(String message) {
                this.message = message;
                return this;
            }
            public Builder setType(MessageType type) {
                this.type = type;
                return this;
            }

            public UserMessage build() {
                return new UserMessage(this);
            }
        }
    }
    public static class FindUserMessageByIdReq {
        public int id;

        public int getId() {
            return id;
        }

        private FindUserMessageByIdReq(Builder builder) {
            id = builder.id;
        }

        public static Builder newBuilder() {
            return new Builder();
        }

        public static final class Builder {
            private int id;

            public Builder() {
            }

            public Builder setId(int id) {
                this.id = id;
                return this;
            }

            public FindUserMessageByIdReq build() {
                return new FindUserMessageByIdReq(this);
            }
        }
    }
    public static class Result {
        public String msg;

        public String getMsg() {
            return msg;
        }
        public int code;

        public int getCode() {
            return code;
        }

        private Result(Builder builder) {
            msg = builder.msg;
            code = builder.code;
        }

        public static Builder newBuilder() {
            return new Builder();
        }

        public static final class Builder {
            private String msg;
            private int code;

            public Builder() {
            }

            public Builder setMsg(String msg) {
                this.msg = msg;
                return this;
            }
            public Builder setCode(int code) {
                this.code = code;
                return this;
            }

            public Result build() {
                return new Result(this);
            }
        }
    }
}

这个模拟类和真实的GRPC类一样，都是用建造者模式来创建对象的。怎么说呢，建造者模式，有好用的地方，也有不好用的地方，好用在于控制对象的创建过程，不好用在于有的时候，只有一两个字段的时候，其实直接new可能更方便，而且，grpc的建造者模式，修改数据真的有点蛋疼。

生成的GRPC请求执行类-模拟

这个类同样也只是模拟类，真正的类是由protobuf-gradle-plugin插件自动生成。grpc的插件其实也就主要为我们自动生成了这两个类而已。

package dest.bean.crm.usercenter;

public class UserPublicGrpc {

    public static UserPublicGrpc newBlockingStub(Object channel) {
        return new UserPublicGrpc();
    }

    public UserOuterClass.UserMessage findUserMessageById(UserOuterClass.FindUserMessageByIdReq findUserMessageByIdReq) {
        return UserOuterClass.UserMessage.newBuilder().build();
    }

    public UserOuterClass.Result addUserMessage(UserOuterClass.UserMessage userMessage) {
        return UserOuterClass.Result.newBuilder().build();
    }

}

生成的GRPC数据转换类

这个类不是模拟类，grpc不会给我们生成这个类，这个类很重要，功能也很简单，就是实现GRPC数据类和自定义实体类之间的互相转换。

有了这个类，我们就真的可以实现，在业务层用自定义实体类，在传输层用GRPC数据类了。额，其实这里还有几个坑，还没有填，比如：

现在grpc和自定义的枚举类是同一个类，这是有问题，还需要优化
涉及到字段的类型也是自定义类的时候，这种简单的转换方式就有问题了，需要将字段的值也用它的类的Mapper转换以便才行，这样的话，我们自动生成的机制就更复杂了，后续优化！！！

package dest.bean.crm.usercenter;

import com.ezbuy.web.GrpcMapper;

public class UserMessageMapper implements GrpcMapper<UserOuterClass.UserMessage, UserMessage> {

    @Override
    public UserOuterClass.UserMessage toGrpc(UserMessage entity) {
        return UserOuterClass.UserMessage.newBuilder()
                .setName(entity.name)
                .setId(entity.id)
                .setMessage(entity.message)
                .setType(entity.type)
                .build();
    }

    @Override
    public UserMessage fromGrpc(UserOuterClass.UserMessage grpc) {
        UserMessage entity = new UserMessage();
        entity.name=grpc.getName();
        entity.id=grpc.getId();
        entity.message=grpc.getMessage();
        entity.type=grpc.getType();
        return entity;
    }
}

这个自动生成的类，实现了我定义的一个接口:GrpcMapper，其实这个接口的作用主要就是一个规范，保证所有的数据转换的方法都是toGrpc和fromGrpc,保证统一。同时也方便后期拓展。

package com.ezbuy.web;

public interface GrpcMapper<Grpc,Entity> {

    Grpc toGrpc(Entity entity);

    Entity fromGrpc(Grpc grpc);
}

之前提到的RxExecuter辅助类，我这里屏蔽掉了AndroidSchedulers.main()，是为了方便在测试时能跑，后续得想个办法测试和正式时，自动决定要不要切换回主线程

package com.ezbuy.web.helper;

import com.ezbuy.functions.Consumer;
import com.ezbuy.functions.Mapper;
import com.ezbuy.web.ServiceFactory;
import com.ezbuy.web.error.BaseConsumer;
import com.ezbuy.web.error.ErrorConsumer;
import io.reactivex.Observable;
import io.reactivex.annotations.NonNull;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;
import io.reactivex.schedulers.Schedulers;

/**
 * yutianran 2018/12/1 下午12:15
 */
public class RxExecuter {

    public static <Request, Response> Disposable execute(Request request, final Consumer<Response> consumer, Mapper<Request, Response> mapper) {
        return Observable.just(request)
                .subscribeOn(Schedulers.io())
                .map(new Function<Request, Response>() {
                    @Override
                    public Response apply(@NonNull Request request) throws Exception {
                        return mapper.map(request);
                    }
                })
                //.observeOn(AndroidSchedulers.main())
                .subscribe(new io.reactivex.functions.Consumer<Response>() {
                    @Override
                    public void accept(Response response) throws Exception {
                        //这里将rx的Consumer接口,转换成我们自己的Consumer接口,是因为我们的Consumer接口可以兼容RpcRequest和GrpcRequest的请求方式
                        if (consumer != null) {
                            consumer.consume(response);
                        }
                    }
                }, new io.reactivex.functions.Consumer<Throwable>() {
                    @Override
                    public void accept(Throwable throwable) throws Exception {
                        //如果有处理onError的BaseConsumer,就用BaseConsumer的onError处理
                        if (consumer != null && consumer instanceof BaseConsumer) {
                            System.out.println("自定义错误处理:" + throwable.getMessage());
                            BaseConsumer baseConsumer = (BaseConsumer) consumer;
                            baseConsumer.onError(throwable);
                            return;
                        }
                        //否则,就用注册在公共服务里面的ErrorConsumer的实现类处理
                        System.out.println("公共错误处理:" + throwable.getMessage());
                        ServiceFactory.getService(ErrorConsumer.class).onError(throwable);
                    }
                });
    }
}

总结

好了，总结一下，我们利用ProtoBuf文件，一共生成了几种文件

基本的解析类：Message、Enum、Service
异步方式的类：WebService、WebServiceImpl、WebServiceTest
兼容GRPC的类：GrpcMapper、GRPC数据模拟类、GRPC请求模拟类

从上面我们可以看到，代码自动生成还是很有用的，尤其是配合我们自己定义的框架和规范来的时候，就更强大的。虽然我们有泛型和反射，可以实现一定的动态性，但是，在实际编写代码的过程中，还是有很多的模式代码的，想要学会偷懒的话，一定得能从日常的开发中，发现模式，然后利用模式来简化日常的开发。泛型是一种运行时的模式，代码自动生成则是一种运行前的模式。

好了，案例篇介绍完毕，敬请期待下一篇：原理篇：利用ProtoBuf文件，一键生成Java代码，看看我们究竟是如何解析ProtoBuf文件，又是如何生成Java代码的。