feat(内核): 支持 Part 文件上传

Author: qianmoQ

.github/workflows/publish-docs.yml

@@ -17,27 +17,10 @@ jobs:
         uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v2
-        with:
-          version: 8
-
-      - name: Get pnpm store directory
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-
-      - uses: actions/cache@v3
-        name: Setup pnpm cache
-        with:
-          path: ${{ env.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
+          cache: 'npm'
 
       - name: Install dependencies
-        run: pnpm install pageforge -g
+        run: npm install pageforge -g
 
       - name: Build
         run: |

README.md

@@ -37,6 +37,8 @@ LightCall 的设计目标是提供一个简单、直观且功能强大的服务
 3. 可扩展性优先
 4. 开发体验至上
 
+## 
+
 ## 贡献指南
 
 我们欢迎任何形式的贡献，包括但不限于：

docs/content/index.md

@@ -1,6 +1,6 @@
 ---
 title: 欢迎使用 LightCall
-layout: home
+template: home
 
 config:
   sidebar: false
@@ -46,10 +46,10 @@ stats:
   title: 用数据说话
   description: 我们取得的成就
   items:
-    - label: 活跃用户
-      value: 1+
-    - label: 服务客户
-      value: 1+
+    - label: Github Stars
+      value: 5+
+    - label: 版本发布
+      value: 2
     - label: 正常运行时间
       value: 99.99%
     - label: 客户满意度

docs/content/usage/part.md

@@ -0,0 +1,49 @@
+---
+title: Part
+---
+
+LightCall 提供了文件上传的支持。
+
+!!! danger "注意"
+
+    LightCall 需要在参数上添加 `@Part` 注解来标识该参数是一个文件上传请求。并且添加 `@Part` 的类必须是一个接口。
+
+!!!
+
+我们使用的模拟数据是，他的代码可以在 [这里](https://github.com/devlive-community/lightcall/blob/dev/src/test/java/org/devlive/lightcall/example/part/PartService.java "PartService" "_blank") 查看。
+
+```java
+public interface PartService
+{}
+```
+
+### 用法
+
+在参数上添加 `@Part` 注解，就可以实现文件上传请求了。
+
+```java
+@Post("/upload")
+String uploadFile(@Part("file") File file);
+```
+
+该示例中的 `uploadFile` 是一个文件上传请求，参数 `file` 表示要上传的文件，`"file"` 是文件参数的名称。请求路径是 `/upload`。
+
+### 文件类型
+
+---
+
+`@Part` 注解支持 `java.io.File` 类型的参数，用于上传本地文件。
+
+```java
+@Post("/upload")
+String apply(@Part("image") File image);
+```
+
+该示例中的 `apply` 方法用于上传图片文件，参数 `image` 表示要上传的图片文件，请求路径是 `/upload`。
+
+!!! info "提示"
+
+    文件上传请求会自动设置 `Content-Type` 为 `multipart/form-data`，并将文件作为表单的一部分上传。
+
+!!!
+```

docs/pageforge.yaml

@@ -41,5 +41,6 @@ nav:
     - /usage/patch
     - /usage/options
     - /usage/head
+    - /usage/part
   - 发布日志:
     - /release/latest

lightcall-core/src/main/java/org/devlive/lightcall/RequestContext.java

@@ -53,10 +53,16 @@ public void setBody(Object body, MediaType mediaType)
             throw new IllegalArgumentException("MediaType cannot be null");
         }
         this.mediaType = mediaType;
-        this.body = RequestBody.create(
-                objectMapper.writeValueAsString(body).getBytes(StandardCharsets.UTF_8),
-                mediaType
-        );
+
+        if (body instanceof RequestBody) {
+            this.body = (RequestBody) body;
+        }
+        else {
+            this.body = RequestBody.create(
+                    objectMapper.writeValueAsString(body).getBytes(StandardCharsets.UTF_8),
+                    mediaType
+            );
+        }
     }
 
     public void setMediaType(MediaType mediaType)

lightcall-core/src/main/java/org/devlive/lightcall/annotation/Part.java

@@ -0,0 +1,18 @@
+package org.devlive.lightcall.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Documented
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Part
+{
+    /**
+     * 文件参数的名称
+     */
+    String value();
+}

lightcall-core/src/main/java/org/devlive/lightcall/handler/ParameterHandlerFactory.java

@@ -18,6 +18,7 @@ public static List<ParameterHandler> createHandlers(
         handlers.add(PathVariableHandler.create());
         handlers.add(HeaderHandler.create(context.getRequestBuilder(), method));
         handlers.add(BodyHandler.create(context));
+        handlers.add(PartHandler.create(context));
         return handlers;
     }
 }

lightcall-core/src/main/java/org/devlive/lightcall/handler/PartHandler.java

@@ -0,0 +1,81 @@
+package org.devlive.lightcall.handler;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import lombok.extern.slf4j.Slf4j;
+import okhttp3.MediaType;
+import okhttp3.MultipartBody;
+import okhttp3.RequestBody;
+import org.devlive.lightcall.RequestContext;
+import org.devlive.lightcall.RequestException;
+import org.devlive.lightcall.annotation.Part;
+
+import java.io.File;
+import java.lang.reflect.Parameter;
+
+@Slf4j
+public class PartHandler
+        implements ParameterHandler
+{
+    private final RequestContext context;
+
+    private PartHandler(RequestContext context)
+    {
+        this.context = context;
+    }
+
+    public static PartHandler create(RequestContext context)
+    {
+        if (context == null) {
+            throw new NullPointerException("RequestContext cannot be null");
+        }
+
+        log.debug("Creating PartHandler");
+        return new PartHandler(context);
+    }
+
+    @Override
+    public boolean canHandle(Parameter parameter)
+    {
+        return parameter.isAnnotationPresent(Part.class);
+    }
+
+    @Override
+    public String handle(Parameter parameter, Object arg, String path)
+    {
+        if (arg == null) {
+            throw new IllegalArgumentException("Part file cannot be null");
+        }
+
+        if (!(arg instanceof File)) {
+            throw new IllegalArgumentException("Parameter annotated with @Part must be a File");
+        }
+
+        Part partAnnotation = parameter.getAnnotation(Part.class);
+        File file = (File) arg;
+
+        MultipartBody.Builder multipartBuilder = new MultipartBody.Builder()
+                .setType(MultipartBody.FORM);
+
+        RequestBody fileBody = RequestBody.create(
+                file,
+                MediaType.parse("application/octet-stream")
+        );
+
+        multipartBuilder.addFormDataPart(
+                partAnnotation.value(),
+                file.getName(),
+                fileBody
+        );
+
+        try {
+            context.setBody(multipartBuilder.build(), MultipartBody.FORM);
+        }
+        catch (JsonProcessingException e) {
+            throw new RequestException("Failed to set form part", e);
+        }
+
+        log.debug("Added file part {}: {}", partAnnotation.value(), file.getName());
+
+        return path;
+    }
+}

lightcall-core/src/test/java/org/devlive/lightcall/example/part/PartService.java

@@ -0,0 +1,12 @@
+package org.devlive.lightcall.example.part;
+
+import org.devlive.lightcall.annotation.Part;
+import org.devlive.lightcall.annotation.Post;
+
+import java.io.File;
+
+public interface PartService
+{
+    @Post("/upload")
+    String apply(@Part("file") File file);
+}