Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

afero

/afero

Pomaga pisać w Go kod systemu plików testowalny dzięki spf13/afero: wstrzykiwanie Fs, testy w pamięci i warstwy tylko do odczytu.

Repozytorium
go-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
05.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 05.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pomaga pisać w Go kod systemu plików testowalny dzięki spf13/afero: wstrzykiwanie Fs, testy w pamięci i warstwy tylko do odczytu.

Oryginalny opis (EN)

Expert skill for testable filesystem code in Go with spf13/afero, authored by its creator. Covers injecting afero.Fs, in-memory tests with MemMapFs, layering with ReadOnlyFs, CopyOnWriteFs and BasePathFs, bridging to io/fs, and where MemMapFs differs from a real disk. Use whenever Go code reads, writes, or walks files and must be unit-tested without touching disk, whenever afero, an injected filesystem, or a --dry-run that must not write is mentioned, and when choosing between afero, io/fs with testing/fstest, and os.Root.

Jak działa

  1. When to Activate
  2. Choose the Interface by What the Code Does
  3. The Pattern: Inject the Fs, Choose It in main
  4. MemMapFs Is Not a Disk
  5. Layering Filesystems
  6. BasePathFs Is Not a Security Boundary
  7. Helpers
  8. Common Mistakes
  9. Installation
Sekcje z nagłówków SKILL.md, w oryginale · 129 linii, 1 098 słów
Podgląd SKILL.md
---
name: afero
description: >
  Expert skill for testable filesystem code in Go with spf13/afero, authored by its creator. Covers
  injecting afero.Fs, in-memory tests with MemMapFs, layering with ReadOnlyFs, CopyOnWriteFs and
  BasePathFs, bridging to io/fs, and where MemMapFs differs from a real disk. Use whenever Go code
  reads, writes, or walks files and must be unit-tested without touching disk, whenever afero, an
  injected filesystem, or a --dry-run that must not write is mentioned, and when choosing between
  afero, io/fs with testing/fstest, and os.Root.
---

# Testable Filesystem Code: afero

Business logic that calls `os` directly can only be tested against a real disk. Inject the filesystem instead, so tests run in memory and production runs on the OS. `github.com/spf13/afero` is the interface for code that writes; `io/fs` is the interface for code that only reads.

Every behavior below was verified against afero v1.15.0 on Go 1.27.

## When to Activate

- Go code reads, writes, creates, renames, or walks files and needs unit tests.
- A test writes temp files only to exercise file-handling logic.
- The code takes an `afero.Fs`, or someone asks how to fake the filesystem.
- A command needs a `--dry-run` that shows what would change without writing.
- Code builds paths under a directory from names it does not control.

## Choose the Interface by What the Code Does

| The code… | Accept | Test with | Production |
| --- | --- | --- | --- |
| only reads | `fs.FS` | `fstest.MapFS` | `os.DirFS(dir)` or `root.FS()` |
| reads and writes | `afero.Fs` | `afero.NewMemMapFs()` | `afero.NewOsFs()` |
| must stay inside a directory, whatever the names | `*os.Root` | `os.OpenRoot(t.TempDir())` | `os.OpenRoot(dir)` |

Read-only code needs no dependency: `io/fs` and `testing/fstest` are the standard library. Reach for afero when the code writes.

## The Pattern: Inject the Fs, Choose It in `main`

```go
type Store struct {
    fs  afero.Fs
    dir string
}

func NewStore(fs afero.Fs, dir string) *Store {
    return &Store{fs: fs, dir: dir}
}

func (s *Store) Save(name string, data []byte) error {
    if err := s.fs.MkdirAll(s.dir, 0o755); err != nil {
        return err
    }
    return afero.WriteFile(s.fs, filepath.Join(s.dir, name), data, 0o644)
}
```

```go
func TestSave(t *testing.T) {
    fs := afero.NewMemMapFs()
    s := NewStore(fs, "/data")
    if err := s.Save("a.txt", []byte("hi")); err != nil {
        t.Fatal(err)
    }
    got, err := afero.ReadFile(fs, "/data/a.txt")
    if err != nil || string(got) != "hi" {
        t.Fatalf("ReadFile = %q, %v", got, err)
    }
}
```

`main` passes `afero.NewOsFs()`. Nothing below `main` imports `os` for file access; one stray `os.WriteFile` makes the in-memory test lie.

## MemMapFs Is Not a Disk

A test that passes on `MemMapFs` proves the logic, not the filesystem contract. Four differences decide whether a green test means anything:

1. **It creates missing parent directories.** `afero.WriteFile(mem, "/no/such/dir/f.txt", …)` succeeds and the directories appear; on `OsFs` the same call fails. A forgotten `MkdirAll` passes every in-memory test. To prove the code creates its directories, run that test on disk: `afero.NewBasePathFs(afero.NewOsFs(), t.TempDir())`.
2. **It does not enforce permission bits.** A file written `0o444` opens for writing and accepts the write. Test permission handling on disk, or with `ReadOnlyFs`.
3. **Rooted and relative paths are different files.** `data/x.txt` and `/data/x.txt` are separate entries. Paths are cleaned (`/data//x.txt`, `/data/./x.txt` and `/data/../data/x.txt` all find `/data/x.txt`), but a leading `/` is never added or removed. Build every path from one absolute root with `filepath.Join`.
4. **It is a weak `fs.FS`.** `afero.NewIOFS(mem)` opens only relative-keyed files (`fs.FS` names never start with `/`), yet `ReadDir(".")` still lists the top directory of a rooted key, which then fails to open. Its files also fail `fstest.TestFS`: a `ReadAt` that runs past end of file returns the bytes it read with a `nil` error where `io.EOF` is required. Test `fs.FS` consumers with `fstest.MapFS`, not a bridged `MemMapFs`.

It is safe for concurrent use: parallel goroutines writing different files pass the race detector, so `t.Parallel` subtests may share one `MemMapFs`.

## Layering Filesystems

| Constructor | Behavior |
| --- | --- |
| `afero.NewReadOnlyFs(fs)` | Every write fails with `EPERM`; `errors.Is(err, os.ErrPermission)` is true. |
| `afero.NewCopyOnWriteFs(base, layer)` | Reads fall through to `base`; writes land in `layer`; `base` is never modified. Removing or renaming a file that `base` holds does not work (see below). |
| `afero.NewBasePathFs(fs, dir)` | Maps every path under `dir`; `/in.txt` is `dir/in.txt`, and `../` above `dir` does not resolve. |
| `afero.FromIOFS{FS: fsys}` | Adapts a read-only `fs.FS` (`embed.FS`, `fstest.MapFS`) to `afero.Fs`; writes fail. |
| `afero.NewIOFS(fs)` | Adapts an `afero.Fs` to `fs.FS` (see the `MemMapFs` caveat above). |

`CopyOnWriteFs` is a dry run for free when the command only creates or overwrites files. It runs its real code against an overlay, then reports what changed, and the disk is untouched:

```go
func run(fs afero.Fs, dryRun bool) (afero.Fs, error) {
    if dryRun {
        fs = afero.NewCopyOnWriteFs(fs, afero.NewMemMapFs())
    }
    return fs, apply(fs) // apply writes through fs; on a dry run only the overlay changes
}
```

It cannot delete or move a file that the base holds. For a file only in the base, `Remove` fails with "file does not exist", `Rename` fails with `EPERM`, and `RemoveAll` returns `nil` while the file stays visible; for a file the command already overwrote, `Remove` returns `nil` and the base copy shows through again. Both are a dry run that reports success for a delete it never staged. A command that deletes or moves files needs its own plan-then-apply step for `--dry-run`.

## `BasePathFs` Is Not a Security Boundary

`BasePathFs` confines *lexical* paths only. It follows symlinks: a link inside the base that points outside it reads the outside file. For names from users, archives, or the network, open the directory with `os.Root` (Go 1.24), which rejects both `../` and symlinks that escape with `path escapes from parent`:

```go
root, err := os.OpenRoot(dir)
if err != nil {
    return err
}
defer root.Close()
data, err := root.ReadFile(name) // Root.ReadFile and Root.WriteFile: Go 1.25
```

Below Go 1.25, use `root.Open` and `root.Create`. To make an untrusted name a safe file name before it reaches the filesystem, see the `fileflow-pathologize` skill.

## Helpers

The package-level helpers take an `Fs` first: `afero.ReadFile`, `afero.WriteFile`, `afero.ReadDir`, `afero.Exists`, `afero.DirExists`, `afero.Walk`, `afero.TempDir`, `afero.Glob`. `afero.Afero{Fs: fs}` wraps the same helpers as methods (`a.Exists(path)`), which reads well when a type uses many of them.

## Common Mistakes

- **Mixing `os` and the injected `Fs`.** One `os.Stat` or `os.ReadFile` in the logic means the test checks a disk the code never wrote to.
- **`afero.NewOsFs()` in a unit test.** It touches the disk, so the test is slow, order-dependent, and leaves files. Use `NewMemMapFs`, or `NewBasePathFs(NewOsFs(), t.TempDir())` when disk behavior is the point.
- **Trusting `MemMapFs` to catch a missing `MkdirAll` or a permission bug.** It cannot; see the four differences.
- **Mixing `data/x` and `/data/x` keys.** The test writes one file and the code reads another.
- **Treating `BasePathFs` as a sandbox.** Symlinks escape it. Use `os.Root`.
- **Accepting `afero.Fs` in read-only code.** Accept `fs.FS`; the caller can pass `os.DirFS`, `embed.FS`, `fstest.MapFS`, or `afero.NewIOFS`.

## Installation

```bash
go get github.com/spf13/afero@latest
```
Pliki w paczce (2)
  • SKILL.md 8 KB
  • .claude-plugin/plugin.json 1 KB

Wersje

W bazie nie ma innych skilli o nazwie afero.

Migawka bazy z 13.11.2026 · wersja paczki 5e4ea751ea19 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 91go
    Pisze, przegląda i refaktoryzuje kod Go zgodnie z idiomami: pakiety, błędy, interfejsy, współbieżność i testy.
  • 100mcp-server-filesystem
    Instaluje serwer MCP systemu plików, który czyta i zapisuje w wydzielonym katalogu lokalnym, oraz obsługuje jego narzędzia.
  • 90esp32-filesystem-full-recovery
    Odzyskuje działanie ESP32 po zapełnieniu systemu plików i ustala zasady usuwania najstarszych danych z pamięci.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.