# alist-java-sdk

**Repository Path**: nyhjw/alist-java-sdk

## Basic Information

- **Project Name**: alist-java-sdk
- **Description**: AList Java SDK 是一个用于与 AList API 交互的 Java 库，封装了 auth、fs、public 和 admin 模块，提供简洁、易用的 Java 接口。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-02-19
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AList Java SDK

[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Maven Central](https://img.shields.io/maven-central/v/com.nyhjw.alist/alist-sdk)](https://central.sonatype.com/artifact/com.nyhjw.alist/alist-sdk)
![JDK Version](https://img.shields.io/badge/JDK-17%2B-red)

📖 [English Version](README.en.md) 

> 现代化、类型安全的 AList API Java 客户端，支持 **同步/异步调用**，适配 Spring 及非 Spring 环境

---

## ✨ 核心特性

- 🚀 **零额外依赖** - 基于 JDK 17+ 内置的 `HttpClient` 实现
- 🔒 **自动认证管理** - 支持用户名密码自动获取/刷新 Token
- 🌐 **完整 API 覆盖** - 100% 实现 `auth`/`fs`/`public`/`admin` 模块
- ⚡ **双模式调用** - 同步 (`send()`) 与异步 (`sendAsync()`) 支持
- 🌱 **环境自适应** - 提供基础 SDK 和 Spring Boot Starter

---
## 📁 目录结构
```
alist-java-sdk/                     # 根目录（Maven 父项目）
 ├── alist-sdk/                      # 核心 SDK（适用于所有 Java 项目）
 │   ├── src/
 │   │   ├── main/java/name/hjw/alist/
 │   │   │   ├── annotation/         # 自定义注解
 │   │   │   ├── api/                # API 接口封装
 │   │   │   ├── client/             # AlistClient 入口类
 │   │   │   ├── config/             # 配置管理（存储 API URL）
 │   │   │   ├── exception/          # 异常处理逻辑
 │   │   │   ├── model/              # 数据模型（DTO）
 │   │   │   ├── utils/              # 工具类
 │   │   ├── test/java/name/hjw/alist/  # 单元测试
 │   ├── pom.xml                      # SDK 模块的 Maven 配置
 │
 ├── alist-spring-boot-starter/       # Spring Boot Starter（适用于 Spring Boot 项目）
 │   ├── src/main/java/name/hjw/alist/spring/
 │   ├── pom.xml                      # Spring Boot Starter 的 Maven 配置
 │
 ├── LICENSE                          # 许可证
 ├── pom.xml                           # Maven 根目录配置（管理依赖）
 ├── README.en.md                      # 英文版文档
 ├── README.md                         # 项目说明文档
```

## 🚀 快速接入
### 基础使用（非 Spring 项目）
#### Maven
```xml
<dependency>
    <groupId>com.nyhjw.alist</groupId>
    <artifactId>alist-sdk</artifactId>
    <version>0.3.1</version>
</dependency>
```
#### 代码示例
#### 1️⃣ 创建客户端
```java
AlistClient client = new AlistClient("https://alist.example.com", "your-token");
```
#### 2️⃣ 同步调用
```java
FsListData data = client.fsApi().list("/");
```

### Spring Boot 项目
#### 添加 Starter
```xml
<dependency>
    <groupId>com.nyhjw.alist</groupId>
    <artifactId>alist-spring-boot-starter</artifactId>
    <version>0.3.1</version>
</dependency>
```

#### 配置示例 (application.yml)

```yaml
alist:
  base-url: "https://alist.example.com"
  username: "your-username"
  password: "your-password"
```

#### 自动注入使用
```java
@RestController
@RequestMapping("/files")
public class FileController {
    @Autowired
    private AlistClient alistClient;

    @GetMapping
    public List<File> listFiles() {
        return alistClient.fs().list("/");
    }
}
```

---

## 🔐 认证机制

所有非公开 API 需携带 JWT Token，SDK 提供两种认证方式：
- **手动指定 Token**
```java
AlistClient client = new AlistClient("https://alist.example.com", "your-token");
```
- **自动凭证认证**（推荐）
```java
// 到期内部自动刷新
AlistClient client = new AlistClient("https://alist.example.com", "your-username", "your-password");
```
---

## ⚡ 高级特性

### 异步调用
```java
CompletableFuture<FsListData> future = client.fsApi().async().list("/");
```

---
## 📜 许可证
本项目采用 **Apache 2.0 许可证**，详情请查看 [LICENSE](LICENSE) 文件。

---

**🚀 AList Java SDK，助你轻松集成 AList API！**