LibOss

LibOss是Elixir实现的一个阿里云OSS的SDK，为Elixir/Phoenix应用提供完整的对象存储解决方案。

特性

支持的功能

快速开始

安装

添加LibOss到你的mix.exs依赖中：

def deps do
  [
    {:lib_oss, "~> 0.3"}
  ]
end

配置

  1. 创建OSS客户端模块: 
defmodule MyApp.Oss do
  use LibOss, otp_app: :my_app
end
  1. 配置访问凭证: 
# config/config.exs
config :my_app, MyApp.Oss,
  endpoint: "oss-cn-beijing.aliyuncs.com",
  access_key_id: System.get_env("OSS_ACCESS_KEY_ID"),
  access_key_secret: System.get_env("OSS_ACCESS_KEY_SECRET")
  1. 在应用的Supervisor中启动: 
# lib/my_app/application.ex
def start(_type, _args) do
  children = [
    MyApp.Oss
  ]
  
  Supervisor.start_link(children, strategy: :one_for_one)
end

基本使用

# 上传文件
{:ok, content} = File.read("document.pdf")
MyApp.Oss.put_object("my-bucket", "docs/document.pdf", content)

# 下载文件
{:ok, content} = MyApp.Oss.get_object("my-bucket", "docs/document.pdf")

# 删除文件
MyApp.Oss.delete_object("my-bucket", "docs/document.pdf")

# 列出文件
{:ok, result} = MyApp.Oss.list_objects_v2("my-bucket", prefix: "docs/")

架构设计

LibOss采用模块化架构，按功能域组织代码，提供清晰的API接口：

lib/
├── lib_oss.ex                 # 主入口模块
├── lib_oss/
│   ├── api/                   # API层（按功能分离）
│   │   ├── object.ex          # 对象操作
│   │   ├── bucket.ex          # 存储桶管理
│   │   ├── multipart.ex       # 分片上传
│   │   ├── acl.ex             # 访问控制
│   │   ├── tagging.ex         # 标签管理
│   │   ├── symlink.ex         # 符号链接
│   │   └── token.ex           # 令牌生成
│   ├── core.ex               # 核心业务逻辑
│   ├── config/               # 配置管理
│   ├── http/                 # HTTP客户端
│   └── model/                # 数据模型

设计特点

高级功能

大文件分片上传

defmodule FileUploader do
  def upload_large_file(bucket, key, file_path) do
    with {:ok, upload_id} <- MyApp.Oss.initiate_multipart_upload(bucket, key),
         {:ok, parts} <- upload_parts(bucket, key, upload_id, file_path),
         :ok <- MyApp.Oss.complete_multipart_upload(bucket, key, upload_id, parts) do
      :ok
    else
      error ->
        MyApp.Oss.abort_multipart_upload(bucket, key, upload_id)
        error
    end
  end
  
  defp upload_parts(bucket, key, upload_id, file_path) do
    file_path
    |> File.stream!([], 5_242_880)  # 5MB chunks
    |> Stream.with_index(1)
    |> Task.async_stream(fn {chunk, part_number} ->
         MyApp.Oss.upload_part(bucket, key, upload_id, part_number, chunk)
       end, max_concurrency: 3)
    |> Enum.reduce_while({:ok, []}, fn
         {:ok, {:ok, etag}}, {:ok, acc} -> 
           {:cont, {:ok, [{part_number, etag} | acc]}}
         _, _ -> 
           {:halt, {:error, :upload_failed}}
       end)
  end
end

前端直传令牌

# 生成前端上传令牌
expire_time = System.system_time(:second) + 3600
conditions = [
  ["content-length-range", 0, 10485760],  # 10MB限制
  ["starts-with", "$key", "uploads/"]     # 路径限制
]

{:ok, token} = MyApp.Oss.get_token("my-bucket", expire_time, conditions)

# 返回给前端的数据
%{
  "OSSAccessKeyId" => token.access_key_id,
  "policy" => token.policy,
  "signature" => token.signature,
  "host" => "https://my-bucket.oss-cn-beijing.aliyuncs.com",
  "key" => "uploads/${filename}"
}

批量操作

# 批量删除文件
files_to_delete = ["temp/file1.txt", "temp/file2.txt", "temp/file3.txt"]
MyApp.Oss.delete_multiple_objects("my-bucket", files_to_delete)

# 批量获取文件信息
files = ["doc1.txt", "doc2.txt", "doc3.txt"]
file_info = files
|> Task.async_stream(fn file ->
     MyApp.Oss.head_object("my-bucket", file)
   end, max_concurrency: 10)
|> Enum.map(fn {:ok, result} -> result end)

配置选项

支持多种配置方式和环境：

config :my_app, MyApp.Oss,
  # 必需配置
  endpoint: "oss-cn-beijing.aliyuncs.com",
  access_key_id: "your_access_key_id", 
  access_key_secret: "your_access_key_secret",
  
  # 可选配置
  timeout: 30_000,           # 请求超时时间
  pool_size: 10,             # 连接池大小
  debug: false               # 调试模式

支持通过环境变量覆盖配置：

export OSS_ENDPOINT="oss-cn-shanghai.aliyuncs.com"
export OSS_ACCESS_KEY_ID="your_key_id"
export OSS_ACCESS_KEY_SECRET="your_secret"

测试

运行测试需要配置有效的OSS凭证：

# 设置测试环境变量
export OSS_ENDPOINT="your-test-endpoint"
export OSS_ACCESS_KEY_ID="your-test-key-id"
export OSS_ACCESS_KEY_SECRET="your-test-secret"

# 运行测试
mix test

# 运行特定测试
mix test test/lib_oss/api/object_test.exs

贡献

欢迎贡献代码和文档！请参考以下步骤：

  1. Fork 项目
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -am 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建Pull Request

许可证

本项目采用 MIT License 许可证。

更新日志

v3.0.x

v0.2.x

v0.1.x

支持

如果您在使用过程中遇到问题：

  1. 搜索 GitHub Issues
  2. 提交新的Issue描述问题
  3. 参考阿里云OSS官方文档