Module: Object Storage Service (OSS)
Relevant source files
The following files were used as context for generating this wiki page:
- zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/controller/AliyunOssController.java
- zheng-oss/zheng-oss-sdk/src/main/resources/applicationContext-oss.xml
- zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/QiniuDemo.java
- zheng-oss/pom.xml
- zheng-oss/zheng-oss-sdk/pom.xml
- zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/controller/DemoController.java
- zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/service/AliyunOssService.java
The Object Storage Service (OSS) module provides a centralized service for managing binary objects, primarily by integrating with third-party cloud storage providers. It is designed to abstract the underlying storage implementation, offering a consistent way for other parts of the zheng application to handle file uploads and retrievals. The module supports both Alibaba Cloud (Aliyun) OSS and Qiniu Cloud Storage.
The architecture is split into several sub-modules, including an SDK for core logic and dependencies, a web component for exposing API endpoints, and an admin interface. This modular design allows for clear separation of concerns and reusability of the storage functionalities across the platform.
Architecture and Components
The zheng-oss module is a parent POM that aggregates three sub-modules, each with a distinct responsibility.
zheng-oss-sdk: Contains the core logic, third-party SDK dependencies (Aliyun and Qiniu), and Spring configuration.zheng-oss-web: A web application that exposes RESTful APIs for storage operations and includes demonstration controllers.zheng-oss-admin: A web application intended for the administration of the OSS module, which depends on thezheng-oss-sdk.
Sources: zheng-oss/pom.xml:23-25, zheng-oss/zheng-oss-admin/pom.xml:19-22, zheng-oss/zheng-oss-web/pom.xml:34-37
The following diagram illustrates the module structure.
Sources: zheng-oss/pom.xml:23-25
Key Dependencies
The zheng-oss-sdk module includes the necessary Java SDKs for interacting with the cloud storage providers.
| Group ID | Artifact ID | Version | Description |
|---|---|---|---|
com.qiniu | qiniu-java-sdk | [7.0.0, 7.1.99] | SDK for Qiniu Cloud Storage. |
com.aliyun.oss | aliyun-sdk-oss | 2.5.0 | SDK for Alibaba Cloud OSS. |
Sources: zheng-oss/zheng-oss-sdk/pom.xml:26-36
Configuration
The core services are configured as Spring beans in applicationContext-oss.xml. This file defines the beans for both Aliyun and Qiniu clients, injecting credentials and configuration properties from an external properties file.
Sources: zheng-oss/zheng-oss-sdk/src/main/resources/applicationContext-oss.xml
Spring Bean Configuration
The following beans are central to the module's operation:
aliyunOssClient: An instance ofcom.aliyun.oss.OSSClient, used for all interactions with Aliyun OSS. It is initialized with the endpoint, access key ID, and secret.qiniuAuth: An instance ofcom.qiniu.util.Auth, which creates authentication credentials for Qiniu API calls.
<!-- applicationContext-oss.xml -->
<!-- 阿里云 -->
<bean id="aliyunOssClient" class="com.aliyun.oss.OSSClient">
<constructor-arg index="0" value="${oss.aliyun.endpoint}"/>
<constructor-arg index="1" value="${oss.aliyun.accessKeyId}"/>
<constructor-arg index="2" value="${oss.aliyun.accessKeySecret}"/>
</bean>
<!-- 七牛云 -->
<bean id="qiniuAuth" class="com.qiniu.util.Auth" factory-method="create">
<constructor-arg index="0" value="${oss.qiniu.accessKey}"/>
<constructor-arg index="1" value="${oss.qiniu.secretKey}"/>
</bean>
Sources: zheng-oss/zheng-oss-sdk/src/main/resources/applicationContext-oss.xml:10-20
Configuration Properties
The bean definitions rely on properties that must be supplied to the Spring context.
| Property Key | Description | Example Value |
|---|---|---|
oss.aliyun.endpoint | The endpoint URL for the Aliyun OSS service. | oss-cn-hangzhou.aliyuncs.com |
oss.aliyun.accessKeyId | The access key ID for Aliyun. | yourAccessKeyId |
oss.aliyun.accessKeySecret | The secret access key for Aliyun. | yourAccessKeySecret |
oss.qiniu.accessKey | The access key for Qiniu. | yourAccessKey |
oss.qiniu.secretKey | The secret key for Qiniu. | yourSecretKey |
Sources: zheng-oss/zheng-oss-sdk/src/main/resources/applicationContext-oss.xml:11-19
Aliyun OSS Integration
The module provides functionalities for both server-side and client-side uploads to Aliyun OSS.
Client-Side Upload Policy
To enable secure uploads directly from a client (e.g., a web browser), the server provides an endpoint to generate a temporary, signed policy. The client can then use this policy to perform the upload.
The AliyunOssController exposes the /aliyun/policy endpoint, which returns a JSON object containing the necessary credentials and policy details for a client-side POST upload.
Sources: zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/controller/AliyunOssController.java:23-28
The following sequence diagram shows the flow of obtaining an upload policy.
Server-Side Operations
The DemoController provides examples of server-side file operations using the aliyunOssClient bean.
Sources: zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/controller/DemoController.java
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /demo/aliyun/upload1 | Uploads a hardcoded string "Hello OSS" as text.txt. |
GET | /demo/aliyun/upload2 | Uploads a local file from d:\\zheng.png as file.png. |
GET | /demo/aliyun/download1 | Downloads text.txt and returns its content as a string. |
GET | /demo/aliyun/download2 | Returns the public URL for file.png. |
GET | /demo/aliyun/upload | Renders a view for client-side uploads, providing the policy from AliyunOssService. |
Sources: zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/controller/DemoController.java:34-80
Upload Flow (Server-Side)
This flowchart illustrates the server-side upload process as seen in /demo/aliyun/upload2.
Qiniu Integration
The QiniuDemo class demonstrates how to integrate with Qiniu for file uploads. It provides methods to generate an upload token and to handle callbacks from Qiniu after an upload is complete.
Sources: zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/QiniuDemo.java
Upload Token Generation
The getUpToken() method uses the qiniuAuth bean to create an upload token. This token grants the client temporary permission to upload a file to a specific Qiniu bucket.
// QiniuDemo.java
@RequestMapping("/upToken")
@ResponseBody
public String getUpToken() {
return qiniuAuth.uploadToken(OssConstant.QINIU_BUCKET_NAME);
}
Sources: zheng-oss/zheng-oss-web/src/main/java/com/zheng/oss/web/QiniuDemo.java:31-35
Upload Callback
Qiniu can be configured to send a callback to a specified server URL after a file upload is successful. The /callback endpoint in QiniuDemo is designed to receive this callback. It verifies the request's authenticity by checking the Authorization header, which is a standard Qiniu callback security measure.
The following sequence diagram illustrates the Qiniu upload and callback process.
Summary
The zheng-oss module effectively encapsulates object storage logic, providing a flexible and extensible solution for file management within the zheng project. By supporting multiple cloud vendors (Aliyun and Qiniu) and offering both client-side and server-side operation patterns, it serves as a robust foundation for any feature requiring file storage. The clear separation into SDK, web, and admin modules promotes maintainability and ease of integration.