Module: Generic API Server

Relevant source files

The following files were used as context for generating this wiki page:

• zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java
• zheng-api/zheng-api-rpc-api/src/main/java/com/zheng/api/rpc/api/ApiService.java
• zheng-api/zheng-api-common/src/main/java/com/zheng/api/common/constant/ApiResult.java
• zheng-api/pom.xml
• zheng-api/zheng-api-server/pom.xml
• zheng-api/zheng-api-rpc-api/pom.xml
• zheng-api/zheng-api-common/pom.xml

The Generic API Server, encapsulated within the zheng-api parent module, functions as a dedicated API gateway for the zheng project. Its primary purpose is to expose a set of RESTful endpoints to external clients, acting as a facade that delegates requests to various backend microservices, such as zheng-upms (User Permission Management System) and zheng-cms (Content Management System), via RPC (Remote Procedure Call).

This module is designed with a clear separation of concerns, consisting of several sub-modules that handle web requests, define service contracts (APIs), and provide common data structures. This architecture promotes loose coupling between the client-facing API layer and the internal service implementations, allowing them to be developed, deployed, and scaled independently. All API responses are standardized using a common wrapper class, ApiResult, ensuring consistent communication with clients.

Architecture

The zheng-api module is a multi-module Maven project. The architecture separates the web layer, the RPC API definitions, the RPC service implementations, and common utilities into distinct modules.

Sources: zheng-api/pom.xml:9-15

Module Structure

The following diagram illustrates the high-level module structure and their dependencies. The zheng-api-server acts as the entry point, consuming services defined in zheng-api-rpc-api which in turn can interact with other backend systems like zheng-cms and zheng-upms.

Component Summary

Module	Packaging	Description
zheng-api-server	war	The web application entry point. Exposes REST endpoints, receives client requests, and is deployed as a web archive. It runs on an embedded Jetty server on port 6666.
zheng-api-rpc-api	jar	Defines the Java interfaces for the RPC services. It acts as a contract between the server and the service implementations and aggregates other RPC APIs like zheng-upms-rpc-api and zheng-cms-rpc-api.
zheng-api-rpc-service	jar	Contains the implementations of the interfaces defined in zheng-api-rpc-api. (Note: Implementation files are not present in the provided context).
zheng-api-common	jar	A utility module containing common classes and constants, such as the standardized ApiResult response object.

Sources: zheng-api/pom.xml, zheng-api/zheng-api-server/pom.xml, zheng-api/zheng-api-rpc-api/pom.xml, zheng-api/zheng-api-common/pom.xml, zheng-api/zheng-api-server/pom.xml:60-62

Request Flow

A typical request to the API server flows from the client through the web controller to the underlying RPC service.

The diagram below shows the sequence for a call to the /api/hello endpoint.

This diagram illustrates how the TestController receives an HTTP request, calls the ApiService interface, and wraps the result in a standardized ApiResult object before sending it back to the client.

Sources: zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java:23-34, zheng-api/zheng-api-rpc-api/src/main/java/com/zheng/api/rpc/api/ApiService.java:10-12

Key Components

zheng-api-server

This module is the public-facing web application. It is configured to run as a WAR file and uses an embedded Jetty server for execution.

Sources: zheng-api/zheng-api-server/pom.xml:13

TestController

The TestController provides a sample API endpoint to demonstrate the functionality of the API server.

*Sources: zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java

Endpoint Definition

Method	Path	Description	Request Param	Response
GET	/api/hello	A test endpoint that returns a greeting string.	name (String): The name to include in the greeting.	An ApiResult object containing the greeting message.

Sources: zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java:27-34

Implementation Snippet

// zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java

@Api(value = "Api接口", description = "Api接口")
@Controller
@RequestMapping("/api")
public class TestController extends BaseController {

	private static Logger _log = LoggerFactory.getLogger(TestController.class);

	@Autowired
	private ApiService apiService;

	@ApiOperation(value = "Api测试")
	@RequestMapping(value = "/hello", method = RequestMethod.GET)
	@ResponseBody
	public Object hello(String name) {
		String result = apiService.hello(name);
		return new ApiResult(ApiResultConstant.SUCCESS, result);
	}

}

Sources: zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java:18-36

zheng-api-rpc-api

This module defines the service contracts.

ApiService Interface

This interface declares the methods available for RPC. The zheng-api-server module uses this interface to interact with the backend services.

// zheng-api/zheng-api-rpc-api/src/main/java/com/zheng/api/rpc/api/ApiService.java

public interface ApiService extends BaseService<Object, BaseExample> {

	/**
	 * Hello World
	 * @param name
	 * @return
	 */
	String hello(String name);

}

Sources: zheng-api/zheng-api-rpc-api/src/main/java/com/zheng/api/rpc/api/ApiService.java:10-12

zheng-api-common

This module provides shared data structures.

ApiResult Class

ApiResult is a generic class used to standardize all API responses. It wraps the actual data with a status code and a message.

The following diagram shows the structure of the ApiResult class.

Fields

Field	Type	Description
code	int	An integer code indicating the status of the response (e.g., 1 for success, 0 for failure).
message	String	A human-readable message describing the result.
data	Object	The actual payload of the response.

Sources: zheng-api/zheng-api-common/src/main/java/com/zheng/api/common/constant/ApiResult.java:11-13