# 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)

📖 [中文文档](README.md)

> Modern, type-safe Java client for AList API with **synchronous/asynchronous** call support, compatible with both Spring and non-Spring environments

---

## ✨ Core Features

- 🚀 **Zero Dependencies** - Built with JDK 17+ native `HttpClient`
- 🔒 **Auto Auth Management** - Automatic token acquisition/refresh with username/password
- 🌐 **Full API Coverage** - 100% implementation of `auth`/`fs`/`public`/`admin` modules
- ⚡ **Dual Call Modes** - Support both synchronous (`send()`) and asynchronous (`sendAsync()`) calls
- 🌱 **Environment Adaptive** - Provides base SDK and Spring Boot Starter

---
## 📁 Directory Structure
```
alist-java-sdk/                     # 根目录（Maven parent project）
 ├── alist-sdk/                      # 核心 SDK (For all Java projects)
 │   ├── src/
 │   │   ├── main/java/name/hjw/alist/
 │   │   │   ├── annotation/         # Custom annotations
 │   │   │   ├── api/                # API interfaces
 │   │   │   ├── client/             # AlistClient entry class
 │   │   │   ├── config/             # Configuration management (API URLs)
 │   │   │   ├── exception/          # Exception handling
 │   │   │   ├── model/              # Data models (DTOs)
 │   │   │   ├── utils/              # Utility classes
 │   │   ├── test/java/name/hjw/alist/  # Unit tests
 │   ├── pom.xml                      #  SDK module Maven config
 │
 ├── alist-spring-boot-starter/       # Spring Boot Starter
 │   ├── src/main/java/name/hjw/alist/spring/
 │   ├── pom.xml                      # Starter module Maven config
 │
 ├── LICENSE                          #  License file
 ├── pom.xml                           # Root Maven config
 ├── README.en.md                      # English documentation
 ├── README.md                         # Chinese documentation
```

## 🚀 Quick Start
### Basic Usage (Non-Spring Projects)
#### Maven
```xml
<dependency>
    <groupId>com.nyhjw.alist</groupId>
    <artifactId>alist-sdk</artifactId>
    <version>0.3.1</version>
</dependency>
```
#### Code Examples
#### 1️⃣ Create Client
```java
AlistClient client = new AlistClient("https://alist.example.com", "your-token");
```
#### 2️⃣ Synchronous Call
```java
FsListData data = client.fsApi().list("/");
```

### Spring Boot Projects
#### Add Starter
```xml
<dependency>
    <groupId>com.nyhjw.alist</groupId>
    <artifactId>alist-spring-boot-starter</artifactId>
    <version>0.3.1</version>
</dependency>
```

#### Configuration (application.yml)

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

#### Auto-injection Usage
```java
@RestController
@RequestMapping("/files")
public class FileController {
    @Autowired
    private AlistClient alistClient;

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

---

## 🔐 Authentication

All non-public APIs require JWT Token. SDK provides two auth modes:
- **Manual Token Specification**
```java
AlistClient client = new AlistClient("https://alist.example.com", "your-token");
```
- **Automatic Credential Auth** (Recommended)
```java
// Auto refresh when expired
AlistClient client = new AlistClient("https://alist.example.com", "your-username", "your-password");
```
---

## ⚡ Advanced Features
### Async Calls
```java
CompletableFuture<FsListData> future = client.fsApi().async().list("/");
```

---

## 📜 License
This project is licensed under **Apache 2.0 License** - see [LICENSE](LICENSE) file for details.

---

**🚀 AList Java SDK - Your Gateway to Seamless AList Integration!**