bookshelf

bookshelf.js

Bookshelf เป็น JavaScript ORM สำหรับ Node.js สร้างขึ้นบนตัวสร้างคิวรี Knex SQL มันมีทั้งอินเทอร์เฟซการโทรกลับตามสัญญาและแบบดั้งเดิมการสนับสนุนการทำธุรกรรมการโหลดความสัมพันธ์ที่กระตือรือร้น/ซ้อนกันความสัมพันธ์ความสัมพันธ์แบบ polymorphic และการสนับสนุนสำหรับความสัมพันธ์แบบหนึ่งต่อหนึ่งต่อหนึ่งและหลายต่อหลายคน

มันถูกออกแบบมาเพื่อทำงานกับ PostgreSQL, MySQL และ SQLITE3

เว็บไซต์และเอกสาร โครงการนี้โฮสต์บน GitHub และมีชุดทดสอบที่ครอบคลุม

การแนะนำ

ชั้นวางหนังสือมีจุดมุ่งหมายเพื่อให้ห้องสมุดง่าย ๆ สำหรับงานทั่วไปเมื่อสอบถามฐานข้อมูลใน JavaScript และสร้างความสัมพันธ์ระหว่างวัตถุเหล่านี้โดยใช้แนวคิดมากมายจากรูปแบบการทำแผนที่ข้อมูล

ด้วย codebase ที่กระชับและมีความรู้หนังสือชั้นวางหนังสือเป็นเรื่องง่ายที่จะอ่านเข้าใจและขยาย มันไม่ได้บังคับให้คุณใช้รูปแบบการตรวจสอบความถูกต้องใด ๆ และให้การโหลดความสัมพันธ์ที่มีประสิทธิภาพและมีประสิทธิภาพที่ยืดหยุ่นและซ้อนกันและการสนับสนุนการทำธุรกรรมชั้นหนึ่ง

มันเป็น Mapper ที่สัมพันธ์กับวัตถุแบบลีนทำให้คุณสามารถเลื่อนลงไปที่อินเทอร์เฟซ Knex ดิบเมื่อใดก็ตามที่คุณต้องการแบบสอบถามที่กำหนดเองซึ่งไม่เหมาะกับการประชุมสต็อก

การติดตั้ง

คุณจะต้องติดตั้งสำเนา KNEX และ mysql , pg หรือ sqlite3 จาก NPM

 $ npm install knex
$ npm install bookshelf

# Then add one of the following :
$ npm install pg
$ npm install mysql
$ npm install sqlite3

ห้องสมุดชั้นวางหนังสือจะเริ่มต้นโดยผ่านอินสแตนซ์ไคลเอนต์ KNEX ที่เริ่มต้น เอกสาร KNEX มีตัวอย่างจำนวนมากสำหรับฐานข้อมูลที่แตกต่างกัน

 // Setting up the database connection
const knex = require ( 'knex' ) ( {
  client : 'mysql' ,
  connection : {
    host     : '127.0.0.1' ,
    user     : 'your_database_user' ,
    password : 'your_database_password' ,
    database : 'myapp_test' ,
    charset  : 'utf8'
  }
} )
const bookshelf = require ( 'bookshelf' ) ( knex )

// Defining models
const User = bookshelf . model ( 'User' , {
  tableName : 'users'
} )

การเริ่มต้นนี้น่าจะเกิดขึ้นเพียงครั้งเดียวในแอปพลิเคชันของคุณ เนื่องจากมันสร้างพูลการเชื่อมต่อสำหรับฐานข้อมูลปัจจุบันคุณควรใช้อินสแตนซ์ชั้น bookshelf ที่ส่งคืนตลอดห้องสมุดของคุณ คุณจะต้องจัดเก็บอินสแตนซ์นี้ที่สร้างขึ้นโดยการเริ่มต้นที่ใดที่หนึ่งในแอปพลิเคชันเพื่อให้คุณสามารถอ้างอิงได้ รูปแบบทั่วไปที่จะติดตามคือการเริ่มต้นไคลเอนต์ในโมดูลเพื่อให้คุณสามารถอ้างอิงได้ในภายหลัง:

 // In a file named, e.g. bookshelf.js
const knex = require ( 'knex' ) ( dbConfig )
module . exports = require ( 'bookshelf' ) ( knex )

// elsewhere, to use the bookshelf client:
const bookshelf = require ( './bookshelf' )

const Post = bookshelf . model ( 'Post' , {
  // ...
} ) 

ตัวอย่าง

นี่คือตัวอย่างที่จะเริ่มต้น:

 const knex = require ( 'knex' ) ( {
  client : 'mysql' ,
  connection : process . env . MYSQL_DATABASE_CONNECTION
} )
const bookshelf = require ( 'bookshelf' ) ( knex )

const User = bookshelf . model ( 'User' , {
  tableName : 'users' ,
  posts ( ) {
    return this . hasMany ( Posts )
  }
} )

const Post = bookshelf . model ( 'Post' , {
  tableName : 'posts' ,
  tags ( ) {
    return this . belongsToMany ( Tag )
  }
} )

const Tag = bookshelf . model ( 'Tag' , {
  tableName : 'tags'
} )

new User ( { id : 1 } ) . fetch ( { withRelated : [ 'posts.tags' ] } ) . then ( ( user ) => {
  console . log ( user . related ( 'posts' ) . toJSON ( ) )
} ) . catch ( ( error ) => {
  console . error ( error )
} ) 

ปลั๊กอินอย่างเป็นทางการ

• เสมือนจริง: กำหนดคุณสมบัติเสมือนจริงในโมเดลของคุณเพื่อคำนวณค่าใหม่
• ตัวแปลงเคส: จัดการการแปลงระหว่างงูของฐานข้อมูลและคุณสมบัติอูฐของโมเดลโดยอัตโนมัติ
• โปรเซสเซอร์: อนุญาตให้กำหนดฟังก์ชั่นโปรเซสเซอร์ที่กำหนดเองที่จัดการกับการแปลงค่าเมื่อใดก็ตามที่เป็น .set() บนโมเดล

ปลั๊กอินชุมชน

• Bookshelf-Cascade-delete-Cascade ลบโมเดลที่เกี่ยวข้องกับการทำลาย
• Bookshelf-Json-Columns-Parse and Stringify คอลัมน์ JSON บนบันทึกและดึงข้อมูลแทนการกำหนดตะขอด้วยตนเองสำหรับแต่ละรุ่น (PostgreSQL และ SQLite)
• Bookshelf-Mask-คล้ายกับฟังก์ชั่นของแอตทริบิวต์ {@link model#savible} แต่รองรับหลายขอบเขตโมเดลการปิดบังและคอลเลกชันโดยใช้ JSON-Mask API
• Bookshelf -Schema - ปลั๊กอินสำหรับการจัดการเขตข้อมูลความสัมพันธ์ขอบเขตและอื่น ๆ
• Bookshelf -Signals - ปลั๊กอินที่แปลเหตุการณ์ชั้นวางหนังสือเป็นศูนย์กลางกลาง
• Bookshelf -Paranoia - ปกป้องฐานข้อมูลของคุณจากการสูญเสียข้อมูลโดยการลบแบบนุ่มนวล
• Bookshelf -UUID - สร้าง UUIDs สำหรับโมเดลของคุณโดยอัตโนมัติ
• Bookshelf -Modelbase - ทางเลือกในการขยาย Model เพิ่มการประทับเวลาการตรวจสอบความถูกต้องของแอตทริบิวต์และวิธีการ CRUD ดั้งเดิม
• Bookshelf-Advanced-Serialization-ปลั๊กอินการมองเห็นที่ทรงพลังยิ่งขึ้นรองรับโมเดลที่เป็นอนุกรมและคอลเลกชันตามสิทธิ์การเข้าถึงบริบทแอปพลิเคชันและหลังจากสร้างความมั่นใจว่าความสัมพันธ์ได้รับการโหลด
• Bookshelf-Plugin-Mode-ปลั๊กอินที่ได้รับแรงบันดาลใจจากฟังก์ชั่นของแอตทริบิวต์ {@link รุ่นที่มองเห็นได้} ช่วยให้สามารถระบุโหมดที่แตกต่างกันด้วยฟิลด์ที่มองเห็นได้/ซ่อนเร้น
• Bookshelf-Secure-Password-ปลั๊กอินสำหรับการรักษาความปลอดภัยรหัสผ่านได้อย่างง่ายดายโดยใช้ bcrypt
• Bookshelf -Bcrypt - ปลั๊กอินอื่นสำหรับการแฮชรหัสผ่านอัตโนมัติสำหรับรุ่นชั้นวางหนังสือของคุณโดยใช้ bcrypt
• Bookshelf-bcrypt.js-ส้อมของชั้นวางหนังสือ-bcrypt โดยใช้ bcryptjs โดยใช้การพึ่งพาน้อยกว่า
• Bookshelf-default-select-เปิดใช้งานการเลือกคอลัมน์เริ่มต้นสำหรับรุ่น แรงบันดาลใจจากฟังก์ชันการทำงานของแอตทริบิวต์ {@link model#visible} แต่ทำงานในระดับฐานข้อมูล
• Bookshelf-Ez-Fetch-วิธีการดึงข้อมูลที่สะดวกซึ่งอนุญาตให้มีการกรองขนาดกะทัดรัดการเลือกความสัมพันธ์และการจัดการข้อผิดพลาด
• Bookshelf -Manager - Model & Collection Manager เพื่อให้ง่ายต่อการสร้างและบันทึกโครงสร้าง JSON ที่ลึกและซ้อนจากคำขอ API
• Bookshelf -Spotparse - ปลั๊กอินที่ทำให้การจัดรูปแบบการแยกวิเคราะห์และการค้นหารุ่นง่ายขึ้น
• Bookshelf -Update - ปลั๊กอินชั้นวางหนังสือง่าย ๆ ที่ช่วยให้การแก้ไขแบบง่าย ๆ ของรุ่นและการอัปเดตข้ามหากไม่มีการเปลี่ยนแปลงค่า

สนับสนุน

มีคำถามเกี่ยวกับห้องสมุดหรือไม่? มาร่วมกับเราในช่อง #bookshelf FreeNode IRC เพื่อรับการสนับสนุนใน knex.js และ bookshelf.js หรือโพสต์ปัญหาเกี่ยวกับสแต็กล้น

การบริจาค

หากคุณต้องการมีส่วนร่วมในชั้นวางหนังสือโดยปกติคุณต้องการรายงานปัญหาหรือส่งคำตอบแบบดึง เพื่อจุดประสงค์นี้พื้นที่เก็บข้อมูลออนไลน์มีอยู่ใน GitHub

สำหรับความช่วยเหลือเพิ่มเติมในการตั้งค่าสภาพแวดล้อมการพัฒนาในท้องถิ่นของคุณหรือเรียนรู้วิธีที่คุณสามารถมีส่วนร่วมในชั้นวางหนังสือคุณควรอ่านเอกสารที่มีส่วนร่วมที่มีอยู่ใน GitHub

คำถามที่พบบ่อย

ฉันสามารถใช้การเรียกกลับสไตล์ node.js มาตรฐานได้หรือไม่?

ใช่คุณสามารถโทร .asCallback(function(err, resp) { บนวิธีการทำงานของฐานข้อมูลใด ๆ และใช้อินเตอร์เฟสการเรียกกลับสไตล์มาตรฐาน (err, result) หากคุณต้องการ

ความสัมพันธ์ของฉันดูเหมือนจะไม่โหลดเกิดอะไรขึ้น?

ตรวจสอบให้แน่ใจว่าได้ตรวจสอบว่าประเภทนั้นถูกต้องสำหรับพารามิเตอร์เริ่มต้นที่ส่งผ่านไปยังโมเดลเริ่มต้นที่ถูกดึง ตัวอย่างเช่น new Model({id: '1'}).load([relations...]) จะไม่คืนค่าเช่นเดียวกับ new Model({id: 1}).load([relations...]) - ประกาศ ว่า ID เป็นสตริงในกรณีหนึ่งและหมายเลขอื่น ๆ นี่อาจเป็นข้อผิดพลาดทั่วไปหากการดึง ID จากพารามิเตอร์ URL

นี่เป็นปัญหาเฉพาะในกรณีที่คุณกระตือรือร้นที่จะโหลดข้อมูลด้วยการโหลดโดยไม่ต้องดึงรุ่นต้นฉบับก่อน new Model({id: '1'}).fetch({withRelated: [relations...]}) ควรทำงานได้ดี

กระบวนการของฉันจะไม่ออกหลังจากสคริปต์ของฉันเสร็จแล้วทำไม?

ปัญหาที่นี่คือ KNEX ซึ่งเป็นเลเยอร์นามธรรมฐานข้อมูลที่ใช้โดยชั้นวางหนังสือใช้การรวมการเชื่อมต่อและทำให้การเชื่อมต่อฐานข้อมูลเปิดอยู่ หากคุณต้องการให้กระบวนการของคุณออกหลังจากสคริปต์ของคุณเสร็จสิ้นคุณจะต้องโทร .destroy(cb) บนคุณสมบัติ knex ของอินสแตนซ์ Bookshelf ของคุณหรือในอินสแตนซ์ Knex ที่ผ่านระหว่างการเริ่มต้น ข้อมูลเพิ่มเติมเกี่ยวกับการรวมการเชื่อมต่อสามารถพบได้ที่เอกสาร KNEX

ฉันจะดีบักได้อย่างไร?

หากคุณผ่าน debug: true ในวัตถุตัวเลือกไปยัง knex เริ่มต้นการโทรคุณสามารถดูการโทรแบบสอบถามทั้งหมดที่ทำ นอกจากนี้คุณยังสามารถผ่านตัวเลือกเดียวกันนั้นไปยังทุกวิธีที่เข้าถึงฐานข้อมูลเช่น model.fetch() หรือ model.destroy() ตัวอย่าง:

 // Turning on debug mode for all queries
const knex = require ( 'knex' ) ( {
  debug : true ,
  client : 'mysql' ,
  connection : process . env . MYSQL_DATABASE_CONNECTION
} )
const bookshelf = require ( 'bookshelf' ) ( knex )

// Debugging a single query
new User ( { id : 1 } ) . fetch ( { debug : true , withRelated : [ 'posts.tags' ] } ) . then ( user => {
  // ...
} )

บางครั้งคุณต้องดำน้ำต่อไปอีกเล็กน้อยและดูว่าทั้งหมดเกิดอะไรขึ้นเบื้องหลัง คุณสามารถใช้ Node-Inspector ซึ่งช่วยให้คุณสามารถดีบักรหัสด้วยคำสั่ง debugger เช่นเดียวกับที่คุณต้องการในเบราว์เซอร์

Bookshelf ใช้สำเนาห้องสมุด Promise bluebird ของตัวเอง คุณสามารถอ่านได้ที่นี่เพื่อดูเพิ่มเติมเกี่ยวกับสัญญาการดีบัก

การเพิ่มบล็อกต่อไปนี้ที่จุดเริ่มต้นของรหัสแอปพลิเคชันของคุณจะจับข้อผิดพลาดใด ๆ ที่ไม่ได้ติดอยู่ในตัวจัดการห่วงโซ่สัญญาปกติซึ่งมีประโยชน์มากในการดีบัก:

 process . stderr . on ( 'data' , ( data ) => {
  console . log ( data )
} )

ฉันจะเรียกใช้ชุดทดสอบได้อย่างไร?

ดูเอกสารที่มีส่วนร่วมใน GitHub

ฉันสามารถใช้ชั้นวางหนังสือนอก node.js ได้หรือไม่?

ในขณะที่มันเป็นเป้าหมายเป็นหลัก node.js การพึ่งพาทั้งหมดนั้นเข้ากันได้กับเบราว์เซอร์และสามารถปรับให้เข้ากับสภาพแวดล้อม JavaScript อื่น ๆ ที่รองรับฐานข้อมูล SQLITE3 โดยการจัดหาอะแดปเตอร์ KNEX ที่กำหนดเอง ไม่มีอะแดปเตอร์ดังกล่าว

โครงการโอเพ่นซอร์สใดที่ใช้ชั้นวางหนังสือ

เราพบโครงการต่อไปนี้โดยใช้ชั้นวางหนังสือ แต่อาจมีอีกมาก:

• ผี (แพลตฟอร์มบล็อก) ใช้ชั้นวางหนังสือ [ลิงก์]
• SOAPEE (การสร้างสบู่ชุมชนและทรัพยากร) ใช้ชั้นวางหนังสือ [ลิงก์]
• Nodeza (Node.js Social Platform สำหรับนักพัฒนาในแอฟริกาใต้) ใช้ชั้นวางหนังสือ [ลิงก์]
• Sunday Cook (แพลตฟอร์มกิจกรรมการทำอาหารเพื่อสังคม) ใช้ชั้นวางหนังสือ [ลิงก์]
• Flyptox (Open-Source Node.js Cryptocurrency Exchange) ใช้ชั้นวางหนังสือ [ลิงก์]
• และแน่นอนทุกอย่างที่นี่ใช้ชั้นวางหนังสือด้วย