|
| 1 | +# {{appName}} |
| 2 | + |
| 3 | +{{appDescription}} |
| 4 | + |
| 5 | +This is a microservice project based on Apache Dubbo, generated by [OpenAPI Generator](https://openapi-generator.tech). |
| 6 | + |
| 7 | +- API version: {{appVersion}} |
| 8 | +- Package version: {{packageVersion}} |
| 9 | +{{^hideGenerationTimestamp}} |
| 10 | +- Generator version: {{generatorVersion}} |
| 11 | +- Build date: {{generatedDate}} |
| 12 | +{{/hideGenerationTimestamp}} |
| 13 | +- Generator: {{generatorClass}} |
| 14 | +{{#externalDocumentationDescription}} |
| 15 | +For more information, please visit: [{{{externalDocumentationDescription}}}]({{{externalDocumentationURL}}}) |
| 16 | +{{/externalDocumentationDescription}} |
| 17 | + |
| 18 | +## Technology Stack |
| 19 | + |
| 20 | +- **Framework**: Apache Dubbo {{dubboVersion}} |
| 21 | +{{#useSpringBoot}} |
| 22 | +- **Spring Boot**: {{#useSpringBoot3}}3.x{{/useSpringBoot3}}{{^useSpringBoot3}}2.x{{/useSpringBoot3}} |
| 23 | +{{/useSpringBoot}} |
| 24 | +- **Java**: {{#java8}}8+{{/java8}}{{^java8}}11+{{/java8}} |
| 25 | +- **Build Tool**: Maven 3.6+ |
| 26 | +- **Registry**: {{registryAddress}} |
| 27 | +- **Serialization**: Jackson JSON |
| 28 | + |
| 29 | +## System Requirements |
| 30 | + |
| 31 | +Building and running this project requires: |
| 32 | +1. Java {{#java8}}8{{/java8}}{{^java8}}11{{/java8}}+ |
| 33 | +2. Maven 3.6+ |
| 34 | +3. Registry Center (Nacos or Zookeeper) |
| 35 | + |
| 36 | +## Quick Start |
| 37 | + |
| 38 | +### 1. Clone and Build Project |
| 39 | + |
| 40 | +```bash |
| 41 | +git clone <your-repo-url> |
| 42 | +cd {{artifactId}} |
| 43 | +mvn clean compile |
| 44 | +``` |
| 45 | + |
| 46 | +### 2. Configure Registry Center |
| 47 | + |
| 48 | +#### Using Nacos (Recommended) |
| 49 | +```bash |
| 50 | +# Download and start Nacos |
| 51 | +wget https://github.com/alibaba/nacos/releases/download/2.2.4/nacos-server-2.2.4.tar.gz |
| 52 | +tar -xzf nacos-server-2.2.4.tar.gz |
| 53 | +cd nacos/bin |
| 54 | +# Linux/Mac |
| 55 | +./startup.sh -m standalone |
| 56 | +# Windows |
| 57 | +startup.cmd -m standalone |
| 58 | +``` |
| 59 | + |
| 60 | +#### Using Zookeeper (Alternative) |
| 61 | +```bash |
| 62 | +# Download and start Zookeeper |
| 63 | +wget https://downloads.apache.org/zookeeper/zookeeper-3.8.2/apache-zookeeper-3.8.2-bin.tar.gz |
| 64 | +tar -xzf apache-zookeeper-3.8.2-bin.tar.gz |
| 65 | +cd apache-zookeeper-3.8.2-bin |
| 66 | +cp conf/zoo_sample.cfg conf/zoo.cfg |
| 67 | +bin/zkServer.sh start |
| 68 | +``` |
| 69 | + |
| 70 | +### 3. Configure Application |
| 71 | + |
| 72 | +Edit the `src/main/resources/application.yml` file: |
| 73 | + |
| 74 | +```yaml |
| 75 | +# Dubbo Configuration |
| 76 | +dubbo: |
| 77 | + application: |
| 78 | + name: {{artifactId}} |
| 79 | + registry: |
| 80 | + # Using Nacos |
| 81 | + address: nacos://127.0.0.1:8848 |
| 82 | + # Or using Zookeeper |
| 83 | + # address: zookeeper://127.0.0.1:2181 |
| 84 | + protocol: |
| 85 | + name: dubbo |
| 86 | + port: 20880 |
| 87 | + provider: |
| 88 | + timeout: 10000 |
| 89 | + |
| 90 | +{{#useSpringBoot}} |
| 91 | +# Spring Boot Configuration |
| 92 | +server: |
| 93 | + port: 8080 |
| 94 | + |
| 95 | +spring: |
| 96 | + application: |
| 97 | + name: {{artifactId}} |
| 98 | + |
| 99 | +# Logging Configuration |
| 100 | +logging: |
| 101 | + level: |
| 102 | + com.alibaba.nacos: WARN |
| 103 | + org.apache.dubbo: INFO |
| 104 | + root: INFO |
| 105 | +{{/useSpringBoot}} |
| 106 | +``` |
| 107 | + |
| 108 | +### 4. Start Application |
| 109 | + |
| 110 | +{{#useSpringBoot}} |
| 111 | +```bash |
| 112 | +# Using Spring Boot Maven plugin |
| 113 | +mvn spring-boot:run |
| 114 | + |
| 115 | +# Or build JAR and run |
| 116 | +mvn clean package |
| 117 | +java -jar target/{{artifactId}}-{{appVersion}}.jar |
| 118 | +``` |
| 119 | +{{/useSpringBoot}} |
| 120 | +{{^useSpringBoot}} |
| 121 | +```bash |
| 122 | +# Build project |
| 123 | +mvn clean compile |
| 124 | + |
| 125 | +# Run main class |
| 126 | +mvn exec:java -Dexec.mainClass="{{package}}.Application" |
| 127 | +``` |
| 128 | +{{/useSpringBoot}} |
| 129 | + |
| 130 | +## Project Structure |
| 131 | + |
| 132 | +``` |
| 133 | +{{artifactId}}/ |
| 134 | +├── src/main/java/{{package}}/ |
| 135 | +{{#operations}} |
| 136 | +│ ├── api/ |
| 137 | +│ │ ├── {{classname}}.java # Service Interface |
| 138 | +│ │ └── {{classname}}DubboImpl.java # Dubbo Service Implementation |
| 139 | +{{/operations}} |
| 140 | +{{#hasModel}} |
| 141 | +│ ├── model/ # Data Models |
| 142 | +{{#models}} |
| 143 | +{{#model}} |
| 144 | +│ │ └── {{classname}}.java |
| 145 | +{{/model}} |
| 146 | +{{/models}} |
| 147 | +{{/hasModel}} |
| 148 | +│ └── Application.java # Main Application Class |
| 149 | +├── src/main/resources/ |
| 150 | +│ └── application.yml # Application Configuration |
| 151 | +├── pom.xml # Maven Configuration |
| 152 | +└── README.md # Project Documentation |
| 153 | +``` |
| 154 | + |
| 155 | +## API Interfaces |
| 156 | + |
| 157 | +{{#apiDocumentationUrl}} |
| 158 | +For complete API documentation, please visit: [{{apiDocumentationUrl}}]({{apiDocumentationUrl}}) |
| 159 | +{{/apiDocumentationUrl}} |
| 160 | + |
| 161 | +### Service Interfaces |
| 162 | + |
| 163 | +{{#operations}} |
| 164 | +#### {{classname}} |
| 165 | +{{#operation}} |
| 166 | +- **{{nickname}}**: {{summary}} |
| 167 | + {{#notes}} |
| 168 | + - Description: {{.}} |
| 169 | + {{/notes}} |
| 170 | +{{/operation}} |
| 171 | + |
| 172 | +{{/operations}} |
| 173 | + |
| 174 | +## Development Guide |
| 175 | + |
| 176 | +### Implement Business Logic |
| 177 | + |
| 178 | +1. Implement specific business logic in the generated `*DubboImpl.java` classes |
| 179 | +2. Inject necessary business service dependencies |
| 180 | +3. Handle exceptions and error scenarios |
| 181 | + |
| 182 | +### Custom Configuration |
| 183 | + |
| 184 | +1. **Timeout Configuration**: Adjust `dubbo.provider.timeout` in `application.yml` |
| 185 | +2. **Thread Pool Configuration**: Configure `dubbo.provider.threads` and other parameters |
| 186 | +3. **Serialization Configuration**: Choose appropriate serialization method |
| 187 | + |
| 188 | +### Monitoring and Operations |
| 189 | + |
| 190 | +1. **Health Checks**: Dubbo provides built-in health check endpoints |
| 191 | +2. **Metrics Monitoring**: Integrate with Prometheus or other monitoring systems |
| 192 | +3. **Log Management**: Configure appropriate log levels and output formats |
| 193 | + |
| 194 | +## Testing |
| 195 | + |
| 196 | +```bash |
| 197 | +# Run unit tests |
| 198 | +mvn test |
| 199 | + |
| 200 | +# Run integration tests |
| 201 | +mvn integration-test |
| 202 | +``` |
| 203 | + |
| 204 | +## Deployment |
| 205 | + |
| 206 | +### Development Environment |
| 207 | +```bash |
| 208 | +mvn spring-boot:run |
| 209 | +``` |
| 210 | + |
| 211 | +### Production Environment |
| 212 | +```bash |
| 213 | +# Build production package |
| 214 | +mvn clean package -Pprod |
| 215 | + |
| 216 | +# Deploy using Docker |
| 217 | +docker build -t {{artifactId}}:{{appVersion}} . |
| 218 | +docker run -p 8080:8080 -p 20880:20880 {{artifactId}}:{{appVersion}} |
| 219 | +``` |
| 220 | + |
| 221 | +## Generator Configuration Options |
| 222 | + |
| 223 | +This project supports the following OpenAPI Generator configuration options: |
| 224 | + |
| 225 | +### Basic Configuration |
| 226 | +- `title`: API service title name (Default: "OpenAPI Dubbo") |
| 227 | +- `basePackage`: Base package name (Default: "org.openapitools") |
| 228 | +- `configPackage`: Configuration class package name (Default: "org.openapitools.configuration") |
| 229 | +- `dubboVersion`: Dubbo version (Default: "3.2.0") |
| 230 | + |
| 231 | +### Generation Control |
| 232 | +- `interfaceOnly`: Generate interfaces only, no implementation classes (Default: false) |
| 233 | +- `serviceInterface`: Generate service interfaces (Default: true) |
| 234 | +- `serviceImplementation`: Generate service implementations (Default: true) |
| 235 | +- `async`: Use asynchronous methods (Default: false) |
| 236 | +- `useTags`: Use tags to create class names (Default: true) |
| 237 | +- `useGenericResponse`: Use generic response wrapper (Default: false) |
| 238 | + |
| 239 | +### Registry Configuration |
| 240 | +- `registry-address`: Registry address, supports full address format (Default: "zookeeper://127.0.0.1:2181") |
| 241 | + - Zookeeper example: `zookeeper://127.0.0.1:2181` |
| 242 | + - Nacos example: `nacos://127.0.0.1:8848` |
| 243 | + |
| 244 | +#### 📋 Automatic Dependency Adaptation by Version |
| 245 | +The generator automatically selects the correct dependencies based on Dubbo version: |
| 246 | + |
| 247 | +**Dubbo 3.2 and earlier versions**: |
| 248 | +- Zookeeper: `dubbo-dependencies-zookeeper` (Aggregation POM) |
| 249 | +- Nacos: `dubbo-registry-nacos` + `nacos-client:2.2.4` |
| 250 | + |
| 251 | +**Dubbo 3.3+ versions**: |
| 252 | +- Zookeeper: `dubbo-registry-zookeeper` + `dubbo-remoting-zookeeper-curator5` |
| 253 | +- Nacos: `dubbo-registry-nacos` + `nacos-client:2.5.0` |
| 254 | + |
| 255 | +### Date-Time Library Configuration |
| 256 | +- `dateLibrary`: Date-time library selection (Default: "java8") |
| 257 | + - `java8`: Java 8 native JSR310 (Recommended, for JDK 1.8+) |
| 258 | + - `java8-localdatetime`: Java 8 using LocalDateTime (For legacy applications only) |
| 259 | + - `joda`: Joda time library (For legacy applications only) |
| 260 | + - `legacy`: Traditional java.util.Date |
| 261 | + |
| 262 | +### Usage Examples |
| 263 | + |
| 264 | +#### 🔧 Dubbo 3.2 Version Example |
| 265 | +```bash |
| 266 | +# Using Zookeeper (3.2 version automatically uses dubbo-dependencies-zookeeper) |
| 267 | +java -jar openapi-generator-cli.jar generate \ |
| 268 | +-i /Users/redoom/IdeaProjects/openapi.yaml \ |
| 269 | +-g dubbo \ |
| 270 | +-o /Users/redoom/IdeaProjects/openapi-test \ |
| 271 | +--additional-properties=registry-address=zookeeper://127.0.0.1:2181 \ |
| 272 | +--additional-properties=dubboVersion=3.2.0 \ |
| 273 | +--additional-properties=dateLibrary=java8 |
| 274 | + |
| 275 | +# Using Nacos (3.2 version uses nacos-client:2.2.4) |
| 276 | +java -jar openapi-generator-cli.jar generate \ |
| 277 | +-i /Users/redoom/IdeaProjects/openapi.yaml \ |
| 278 | +-g dubbo \ |
| 279 | +-o /Users/redoom/IdeaProjects/openapi-test \ |
| 280 | +--additional-properties=registry-address=nacos://127.0.0.1:8848 \ |
| 281 | +--additional-properties=dubboVersion=3.2.0 \ |
| 282 | +--additional-properties=dateLibrary=java8 |
| 283 | +``` |
| 284 | + |
| 285 | +#### 🚀 Dubbo 3.3+ Version Example |
| 286 | +```bash |
| 287 | +# Using Zookeeper (3.3+ version automatically uses new modular dependencies) |
| 288 | +java -jar openapi-generator-cli.jar generate \ |
| 289 | +-i /Users/redoom/IdeaProjects/openapi.yaml \ |
| 290 | +-g dubbo \ |
| 291 | +-o /Users/redoom/IdeaProjects/openapi-test \ |
| 292 | +--additional-properties=registry-address=zookeeper://127.0.0.1:2181 \ |
| 293 | +--additional-properties=dubboVersion=3.3.0 \ |
| 294 | +--additional-properties=dateLibrary=java8 |
| 295 | + |
| 296 | +# Using Nacos (3.3+ version uses nacos-client:2.5.0) |
| 297 | +java -jar openapi-generator-cli.jar generate \ |
| 298 | +-i /Users/redoom/IdeaProjects/openapi.yaml \ |
| 299 | +-g dubbo \ |
| 300 | +-o /Users/redoom/IdeaProjects/openapi-test \ |
| 301 | +--additional-properties=registry-address=nacos://127.0.0.1:8848 \ |
| 302 | +--additional-properties=dubboVersion=3.3.0 \ |
| 303 | +--additional-properties=dateLibrary=java8 |
| 304 | +``` |
| 305 | + |
| 306 | +## Troubleshooting |
| 307 | + |
| 308 | +### Common Issues |
| 309 | + |
| 310 | +1. **Registry Connection Failed** |
| 311 | + - Check if the registry center is started |
| 312 | + - Verify network connection and port configuration |
| 313 | + |
| 314 | +2. **Service Call Timeout** |
| 315 | + - Adjust `dubbo.provider.timeout` settings |
| 316 | + - Check network latency and service performance |
| 317 | + |
| 318 | +3. **Serialization Exception** |
| 319 | + - Ensure all model classes implement `Serializable` interface |
| 320 | + - Check Jackson configuration |
| 321 | + |
| 322 | +### Debug Logging |
| 323 | + |
| 324 | +Enable debug mode to see detailed logs: |
| 325 | + |
| 326 | +```yaml |
| 327 | +logging: |
| 328 | + level: |
| 329 | + org.apache.dubbo: DEBUG |
| 330 | + {{package}}: DEBUG |
| 331 | +``` |
| 332 | + |
| 333 | +## License |
| 334 | + |
| 335 | +This project is licensed under the [Apache License 2.0](LICENSE). |
| 336 | + |
| 337 | +## Contributing |
| 338 | + |
| 339 | +Issues and Pull Requests are welcome! |
| 340 | + |
| 341 | +## Contact |
| 342 | + |
| 343 | +{{#apiDocumentationUrl}}{{infoEmail}}{{/apiDocumentationUrl}} |
| 344 | + |
| 345 | +--- |
| 346 | + |
| 347 | +> This project is automatically generated by OpenAPI Generator, based on Apache Dubbo microservice architecture. |
0 commit comments