# bytenexus-java-sdk

**Repository Path**: llakcs/bytenexus-java-sdk

## Basic Information

- **Project Name**: bytenexus-java-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ByteNexus Java SDK

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.7-6DB33F?logo=springboot)](https://spring.io/projects/spring-boot)
[![JDK](https://img.shields.io/badge/JDK-17+-ED8B00?logo=openjdk)](https://openjdk.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

ByteNexus 对象存储服务的 Java 客户端 SDK，基于 **Spring Boot 3.2**，以 Starter 形式自动装配，零配置即可注入使用。

## 功能

| 分类 | 功能 | API 接口 |
|------|------|----------|
| 基础操作 | 普通上传 | `POST /api/open/file/upload` |
| 基础操作 | 文件下载（含SSE解密） | `GET /api/open/file/download` |
| 基础操作 | 文件删除 | `DELETE /api/open/file/delete` |
| 基础操作 | 文件列表（前缀+分页） | `GET /api/open/file/list` |
| 分段上传 | 初始化分段 | `POST /api/open/file/multipart/init` |
| 分段上传 | 上传分段 | `PUT /api/open/file/multipart/part` |
| 分段上传 | 合并完成 | `POST /api/open/file/multipart/complete` |
| 分段上传 | 取消上传 | `DELETE /api/open/file/multipart/abort` |
| SDK增强 | 自动分段上传 | 大文件自动判断并走分段流程 |

---

## 环境要求

- **JDK** 17+
- **Spring Boot** 3.2+
- **Maven** 3.6+

## 依赖

| 依赖 | 说明 |
|------|------|
| `spring-boot-starter` | Spring Boot 核心 |
| `spring-boot-starter-web` | RestTemplate HTTP 客户端 |
| `spring-boot-configuration-processor` | IDE 配置提示 |
| `lombok` | 代码简化 |

---

## 安装

### Maven

```xml
<dependency>
    <groupId>com.bytenexus</groupId>
    <artifactId>bytenexus-java-sdk</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

### Gradle

```groovy
implementation 'com.bytenexus:bytenexus-java-sdk:1.0.0-SNAPSHOT'
```

---

## 配置

```yaml
# application.yml
bytenexus:
  server-url: http://localhost:8080     # 必填：服务地址
  app-id: your-app-id                   # 必填：AccessKey AppID
  app-secret: your-app-secret           # 必填：AccessKey AppSecret
  bucket-name: my-bucket                # 可选：默认 Bucket
  timeout: 30s                          # 可选：请求超时，默认 30s
  part-size: 5242880                    # 可选：分段大小，默认 5MB
```

> `server-url`、`app-id`、`app-secret` 为必填项，缺失则不会自动装配 `ByteNexusClient` Bean。

---

## 快速开始

### 方式一：配置默认 Bucket，操作省略

```java
@Service
public class FileService {

    @Autowired
    private ByteNexusClient client;

    public void demo() {
        // 上传（使用默认 bucket）
        UploadResult result = client.upload("/path/to/photo.jpg", "photos/photo.jpg");

        // 下载
        DownloadResult data = client.download("photos/photo.jpg");

        // 保存到文件
        client.downloadToFile("photos/photo.jpg", "./downloaded.jpg");

        // 删除
        client.delete("photos/photo.jpg");
    }
}
```

### 方式二：不配 bucket-name，每次操作必传

```yaml
# application.yml
bytenexus:
  server-url: http://localhost:8080
  app-id: your-app-id
  app-secret: your-app-secret
  # bucket-name 不配
```

```java
// 每次操作必须显式传入 bucket
UploadResult result = client.upload("/path/to/file.jpg", "photo.jpg", "my-bucket");
DownloadResult data = client.download("photo.jpg", "my-bucket");
```

### 方式三：运行时切换 Bucket

```java
client.setBucket("another-bucket");
client.upload("/path/to/file.txt", "file.txt", null);

String current = client.getBucket(); // "another-bucket"
```

### 方式四：手动创建多 Bucket 实例

```java
ByteNexusProperties props = new ByteNexusProperties();
props.setServerUrl("http://localhost:8080");
props.setAppId("app-id");
props.setAppSecret("secret");
props.setBucketName("bucket-b");

ByteNexusClient customClient = new ByteNexusClient(props);
```

---

## Bucket 配置规则

| 配置 bucket-name | 方法参数 bucketName | 结果 |
|:---:|:---:|---|
| ✅ 已配置 | `null` | 使用默认值 |
| ✅ 已配置 | 传入具体值 | 传入值覆盖默认值 |
| ❌ 未配置 | 传入具体值 | 使用传入值 |
| ❌ 未配置 | `null` | **抛出 `IllegalStateException`** |

---

## API 参考

### 基础操作

```java
// 上传文件
UploadResult upload(String filePath, String objectKey)
UploadResult upload(String filePath, String objectKey, String bucketName)
UploadResult uploadWithBucket(String filePath, String objectKey, String bucketName)

// 下载到内存
DownloadResult download(String objectKey)
DownloadResult download(String objectKey, String bucketName)

// 下载到本地文件
void downloadToFile(String objectKey, String localPath)
void downloadToFile(String objectKey, String localPath, String bucketName)

// 删除文件
void delete(String objectKey)
void delete(String objectKey, String bucketName)

// 列出文件
ListResult listFiles(String prefix, String marker, int maxKeys)
ListResult listFiles(String prefix, String marker, int maxKeys, String bucketName)

// 分页遍历全部文件
void listAllFiles(String prefix, String bucketName, Consumer<List<ObjectInfo>> callback)
```

### 分段上传

```java
// 初始化
MultipartInitResult initMultipartUpload(String objectKey, String bucketName)

// 上传分段
MultipartPartResult uploadPart(String uploadId, int partNumber, byte[] data, String bucketName)

// 完成
MultipartCompleteResult completeMultipartUpload(String uploadId, List<PartInfo> parts, String bucketName)

// 取消
void abortMultipartUpload(String uploadId, String bucketName)
```

### SDK 增强

```java
// 自动分段上传（小文件普通上传，大文件自动分段）
MultipartCompleteResult autoMultipartUpload(String filePath, String objectKey, String bucketName)
```

### Bucket 管理

```java
void setBucket(String bucketName)   // 切换默认 bucket
String getBucket()                   // 获取当前默认 bucket
```

---

## 分段上传示例

```java
// 方式一：手动控制
MultipartInitResult init = client.initMultipartUpload("bigfile.zip", "my-bucket");
byte[] part1 = readPart();
byte[] part2 = readPart();

client.uploadPart(init.getUploadId(), 1, part1, "my-bucket");
client.uploadPart(init.getUploadId(), 2, part2, "my-bucket");

List<PartInfo> parts = List.of(new PartInfo(1, ""), new PartInfo(2, ""));
MultipartCompleteResult result = client.completeMultipartUpload(init.getUploadId(), parts, "my-bucket");

// 方式二：自动分段
MultipartCompleteResult result = client.autoMultipartUpload("/path/to/bigfile.zip", "bigfile.zip", "my-bucket");
```

---

## 鉴权机制

SDK 自动处理签名鉴权，无需手动计算。签名算法：

```
Signature = HMAC-SHA256(AppSecret, AppID + Timestamp + HTTP_Method + Path)
```

请求头：
- `AppID` - 应用 ID
- `Timestamp` - Unix 时间戳（秒）
- `Signature` - 签名结果
- `BucketName` - Bucket 名称

---

## 项目结构

```
bytenexus-java-sdk/
├── pom.xml
├── README.md
└── src/main/
    ├── java/com/bytenexus/sdk/
    │   ├── ByteNexusClient.java              # 客户端核心实现
    │   ├── ByteNexusProperties.java          # 配置属性
    │   ├── ApiResponse.java                  # 通用响应
    │   ├── autoconfigure/
    │   │   └── ByteNexusAutoConfiguration.java  # Spring Boot 自动装配
    │   └── model/
    │       ├── UploadResult.java             # 上传结果
    │       ├── DownloadResult.java           # 下载结果
    │       ├── ObjectInfo.java               # 文件信息
    │       ├── ListResult.java               # 列表结果
    │       ├── MultipartInitResult.java      # 分段初始化结果
    │       ├── MultipartPartResult.java      # 分段上传结果
    │       ├── MultipartCompleteResult.java  # 分段完成结果
    │       └── PartInfo.java                 # 分段信息
    └── resources/META-INF/spring/
        └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
```

---

## License

MIT