RIP-25 Ease of Use Improvements on RocketMQ Client API
* Current Status: Draft * Authors: caigy https://github.com/caigy * Shepherds: duhengforever duhengfore...@apache.org * Mailing List discussion: dev@rocketmq.apache.org * Pull Request: #PR_NUMBER * Released: <released_version> Background & Motivation ________________________________ What do we need to do * will we add a new module? No. * will we add new APIs? Yes. * will we add new feature? No. Why should we do that * Are there any problems of our current project? Currently, RocketMQ's client API is a bit complex, and there exists some unreasonable encapsulation. For example: ** There are 20 methods for sending messages in DefaultProducer, with lack of encapsulation, which increases complexity in usage. ** DefaultMQPushConsumer provides 10 constructors，which may make user difficult to choose one. ** Class Message provides constructors with and without arguments, and also provides getters/setters to operate fields of it, which lacks good separation of required and non-required arguments. API is important media for users to interact with RocketMQ, and it is worth investing effort in optimizing its design. * What can we benefit proposed changes? Provide clear and easier-to-understand API of RocketMQ, make it easier to use, especially for beginners. Goals ________________________________ * What problem is this proposal designed to solve? Optimize RocketMQ client APIs, including Producer, Consumer and Message, remove unnecessary APIs, and provide better encapsulation. Current unreasonable APIs will be marked deprecated and will be removed in the future. After this optimization, the APIs should keep as stable as possible. * To what degree should we solve the problem? We wish developers can use RocketMQ more easily with new APIs. Non-Goals ________________________________ * What problem is this proposal NOT designed to solve? This proposal will NOT change feature and performance. * Are there any limits of this proposal? Nothing specific. Changes ________________________________ * Architecture No architecture changes in this proposal. * Interface Design/Change ** Method signature changes. Yes. For example: *** Add generic to support data type of message body in Message. *** Support chain-call instantiation of Producer, Consumer, Message, eg：Message<String>.builder().topic("msg topic").body("msg body").build(); *** Producer provides unified and stable send() API, which is like write() method of UNIX file I/O. *** Add asynchronous message consumption API based on CompletableFuture in Consumer. *** etc... ** Method behavior changes. No. CLI command changes. No. ** Log format or content changes. No. * Compatibility, Deprecation, and Migration Plan ** Are backward and forward compatibility taken into consideration? Optimized APIs should NOT affect compatibility, some APIs would be marked deprecated. New features will use optimized APIs, encouraging users not to use deprecated APIs. ** Are there deprecated APIs? Yes. Some unreasonable APIs will be deprecated in this RIP. ** How do we do migration? Unreasonable APIs are marked deprecated in this proposal, and will be removed in the future. * Implementation Outline We will implement the proposed changes by 1 phase. Phase 1 1. Collect pain points in using RocketMQ client APIs and redesign them. 2. Optimize those APIs. 3. Mark previous APIs deprecated.
