Hành trình xây dựng chỉ mục có thể tìm kiếm của chúng tôi với Algolia và NodeJS

Tôi đã hợp tác với Kỹ sư Full Stack của Starschema, Soma Osvay, để viết về một dự án gần gũi và thân thiết đối với tôi: tài liệu dành cho nhà phát triển. Cả tôi và Soma đều hy vọng bạn thích bài viết này, nơi chúng tôi đề cập đến trường hợp sử dụng và các thách thức cũng như cách triển khai mà Soma đã đưa ra.

Tại Starschema, chúng tôi có rất nhiều dự án mà chúng tôi đã thực hiện như một phần của quá trình tư vấn với tài liệu đánh dấu . Khi chúng tôi đang hỗ trợ các giải pháp hiện có này hoặc muốn phát triển một dự án mới, chúng tôi thường muốn tìm kiếm trong tất cả các tài liệu. Chúng tôi hiện không có giải pháp, khiến chúng tôi tốn hàng giờ đồng hồ vì chúng tôi phải thực hiện công việc này theo cách thủ công.

Trường hợp sử dụng

Chúng tôi cần có khả năng tìm kiếm các dự án liên quan đến các chủ đề cụ thể để kiểm tra các chi tiết triển khai cụ thể, lấy ý tưởng từ mã, v.v. Nhóm Bán hàng cũng cần một giải pháp để xác định loại dự án nào mà nhóm của chúng tôi đã hoàn thành cho các chủ đề nhất định và có thể nhanh chóng thông báo lại cho khách hàng tiềm năng.

Sẽ thật tuyệt nếu có thứ gì đó giống như Stack Overflow nội bộ dành cho Nhà phát triển của chúng tôi vì chúng tôi đang thực hiện rất nhiều công việc kỹ thuật chuyên sâu trong Tableau. Người quản lý dự án cũng cần có khả năng xác định nhân viên nào đã làm việc với một số công nghệ nhất định để họ có thể nhận được câu trả lời nhanh chóng và dễ dàng cho các câu hỏi.

Nói tóm lại, chúng ta cần có khả năng tìm kiếm các dự án của riêng mình dựa trên các thuộc tính sau:

1. Công nghệ được sử dụng (ngôn ngữ mã hóa, cơ sở dữ liệu, v.v.)
2. Từ khóa dự án (thẻ)
3. Bản thân tài liệu dự án như hướng dẫn cài đặt, tài liệu kỹ thuật, v.v.
4. Khung thời gian khi dự án xảy ra

Tất cả các thuộc tính này tồn tại trong các tệp đánh dấu tài liệu nội bộ – chúng tôi chỉ cần một cách để tìm kiếm chúng.

Kế hoạch thực hiện

Kế hoạch là sử dụng NodeJS CLI làm bằng chứng về khái niệm sẽ:

1. Quét các kho lưu trữ công cộng GitHub hàng đầu và lấy tệp đánh dấu README (cuối cùng sẽ đại diện cho các dự án nội bộ của chúng tôi)
2. Lưu trữ các tệp tài liệu vào Algolia cùng với thông tin cơ bản của dự án (tiêu đề, (các) ngôn ngữ lập trình, thẻ, v.v.)

CLI sẽ chứa các đối số dòng lệnh và ghi nhật ký nâng cao để dễ sử dụng. Chúng tôi cũng muốn lưu trữ nó trên web để mọi người có thể dùng thử.

Thử thách

Thách thức lớn nhất hiện tại là kích thước bản ghi — Algolia chỉ cho phép các bản ghi của chúng tôi tối đa là 100KB. Tuy nhiên, hầu hết các tệp tài liệu đánh dấu đều lớn hơn nhiều. Giải pháp là chúng ta cần chia các tệp đánh dấu thành nhiều phần trong Chỉ mục. Sau đó, chúng tôi cũng cần đảm bảo rằng khi chúng tôi tìm kiếm thứ gì đó, một dự án chỉ xuất hiện một lần—ngay cả khi nó được chia thành nhiều bản ghi.

May mắn thay, Algolia có một tính năng riêng biệt nên chúng tôi có thể loại bỏ các kết quả trùng lặp này một cách dễ dàng.

Triển khai bộ lập chỉ mục

Để làm cho việc sử dụng Trình lập chỉ mục trở nên dễ dàng nhất có thể, tôi đã chọn tạo CLI cho nó như đã đề cập ở trên. Sau khi cung cấp các đối số cần thiết, công cụ sẽ tự động khởi tạo kho lưu trữ, xóa mọi bản ghi hiện có và định cấu hình cài đặt mức độ liên quan.

Cung cấp năng lượng cho công cụ là một API GitHub đơn giản, lấy số lượng kho lưu trữ hàng đầu được yêu cầu và trích xuất tất cả siêu dữ liệu của chúng và tải xuống tệp README. Nó cũng sẽ lọc ra các kho lưu trữ thiếu chủ sở hữu hoặc thiếu tệp README, mang lại cho chúng tôi kết quả tốt nhất. Cuối cùng, nó cũng sẽ chuyển đổi nội dung đánh dấu sang HTML để hiển thị dễ dàng hơn ở giao diện người dùng.

Để kiểm tra kích thước bản ghi, công cụ sẽ tự động chia các README hơn 50 nghìn ký tự thành các bản ghi bổ sung. Bằng cách này, các bản ghi sẽ không quá lớn nhưng một bản ghi vẫn sẽ phục vụ hầu hết tất cả các kho lưu trữ. Sau đó, nó sẽ đồng bộ hóa thông tin này với 100 bản ghi Algolia cùng một lúc để chúng tôi có thể đáp ứng các đề xuất theo lô của chúng như được mô tả ở đây trong tài liệu.

Triển khai giao diện người dùng

Để làm điểm khởi đầu, tôi đã tận dụng thư viện ứng dụng tạo-tìm kiếm tức thì do Algolia phát hành và khởi chạy bản tóm tắt InstantSearch.js. Từ đây, tôi có thể thêm các tiện ích bổ sung do InstantSearch.js cung cấp, chẳng hạn như phân trang và bộ chọn kích thước trang hoạt động rất tốt.

Vì chúng tôi cũng đã thu thập siêu dữ liệu kho lưu trữ bằng đánh dấu, nên chúng tôi cũng cần tùy chỉnh thành phần lượt truy cập để bao gồm thông tin bổ sung này. Thông thường, siêu dữ liệu cũng quan trọng như mô tả thư viện để các nhà phát triển có thể xem nhanh liệu đó có phải là một thư viện phổ biến hay không, ai đã phát hành nó, các thẻ, v.v. Tôi cũng đã thêm các khía cạnh để Người dùng có thể lọc theo ngôn ngữ lập trình, thẻ hoặc số lần nó đã được phân nhánh.

Phần cuối cùng của câu đố là thêm nút 'Mở tài liệu' cho phép bạn đọc nhanh chóng và dễ dàng nội dung đánh dấu cho kho lưu trữ trong cửa sổ bật lên mà không cần rời khỏi ứng dụng. Nếu bản ghi chúng tôi đang nhấp vào có nhiều hàng, nó sẽ tự động tải các bản ghi bổ sung và nối chúng trong màn hình—tuyệt vời!

Phần kết luận

Dự án này là một thử nghiệm thú vị và thực sự cho tôi thấy Algolia linh hoạt như thế nào đối với các trường hợp sử dụng khác nhau chẳng hạn như trường hợp của chúng tôi. Các tiện ích sẵn sàng hoạt động giúp tôi tiết kiệm rất nhiều thời gian trong quá trình tạo mẫu và việc có được kết quả phù hợp từ một vài lần nhấn phím đầu tiên là điều cực kỳ ấn tượng. Tôi cũng nghĩ sẽ cực kỳ thú vị nếu chúng tôi có thể khai thác sức mạnh của Algolia Recommend nếu chúng tôi có thể tạo đủ sự kiện từ việc Người dùng nhấp vào dự án trong nội bộ.

Bạn có thể xem bản demo trực tiếp của dự án thử nghiệm GitHub tại đây , với một nút sẽ thiết lập cho bạn thông tin xác thực bản demo mặc định để xem chỉ mục của chúng tôi. Quan tâm đến mã lập chỉ mục phụ trợ? Bạn có thể tìm thấy nó ở đây trên GitHub!

Cũng được xuất bản ở đây.